Default perspective view looking forwards, 100 degrees horizontal field of view.


fish2persp -w 800 -a 3

The vertical aperture is automatically adjusted to match the width and height.Controls are provided for any angle fisheye as well as fisheyes that are notlevel or tilted, noting that the exact order of the correction rotations mayneed to be considered for particular cases.Note that a perspective projection is not defined for greater than 180 degrees,indeed it gets increasingly inefficient past around 140 degrees.The field of view can be adjusted as well as the viewing direction.The following example is a 120 degrees horizontal field of view and looking upwards by 30 degrees.


fish2persp -w 800 -a 3 -x 30 -t 120

If 'straight' lines are not straight that normally means the fisheye center or radius are not specified correctly or the angle is not defined correctly.Curvature in what should be straight lines near the rim of the fisheye normally meansthe fisheye lens has non-linearities near the rim (a deviation from the mathematically purefisheye projection) and corrections need to be applied.The following is looking right by 40 degrees and a narrower field of view of 80 degrees.


fish2persp -w 800 -a 3 -z 40 -t 80

The center of the fisheye on the input image can be found by projectinglines along vertical structure in the scene. Where these lines intersectis a close approximation to the center of the fisheye, assuming thecamera is mounted vertically. Alternatively, and perhaps easier, is to identify the edges of thefisheye and assume a perfect circular inscribed circle. Note that for the example utilities providedhere the origin is assumed to be the bottom left corner, unlike the more common top right thatimage editing programs use.

To test the algorithm a fisheye rendering inside a gridded cube is a good example,see image on left below. Any correct perspective projection should result in straight lines.


Sample input image




Front fisheye to panorama

Now superceeded by fish2pano
Software: frontfish2pano

Update November 2016: frontfish2pano is now redundant, fisheye orientation cannow be controlled with fish2pano, see later.

This case is developed mainly for 'front pointing' fisheyes although it does have applicationfor other orientations. The projection is more correctly called a cylindrical panorama.

Source fisheye image.

Transformation with the default settings is shown below.


frontfish2pano -a 3 -w 800

Correct for the fact that the camera is not quite horizontal, this is thereason the vertical structure doesn't appear vertical in the panoramic projection.Of course nothing is for free, one looses a bit of the image in the bottomleft and right corners.

Stitcher

frontfish2pano -a 3 -w 800 -fa -20

Set the vertical field of view of the panorama, in the following cases narrowed fromthe default of 100 degrees to 80 degrees. As with perspective projections there is a limit, in this case, to the vertical field of view, a hard limit at 180 degrees but increasingly inefficientpast 140 degrees.


frontfish2pano -a 3 -w 800 -fa -20 -ap 80

Fisheye to (partial) spherical projection

Additional notes on the algorithm
Software: fish2sphere

Updates 2017

Updates 2018

Source fisheye image.

Transformation using the default settings. Since a 180 degree (in this case) fisheyecaptures half the visible universe from a single position, so it makes sense that it occupieshalf of a spherical (equirectangular) projection, which captures the entire visibleuniverse from a single position.

In this case the camera is not perfectly horizontal, this and other adjustmentscan be made. In the example here the lens was pointing downwards slightly, thecorrection results in more of the south pole being visible and less of the northpole.

Note that the fisheye angle is not limited to 180 degrees, indeed one applicationfor this is in the pipeline to create 360 spherical panoramas from 2 cameras, eachwith a fisheye lens with a field of view greater than 180 to provide a blend zone.

This can be readily implemented in the OpenGL Shader Language, the followingexample was created in the Quartz Composer Core Image Filter.

The transformation can be performed in realtime using warp mesh files forsoftware such as warpplayer or the VLC equivalent VLCwarp. A sample mesh file is givenhere: fish2sph.data. Showing the result in actionis below.

Test cases for various fisheye apertures.
180 degree fisheye
120 degree fisheye
220 degree fisheye
220 degree fisheye and 90 degree latitude rotation
220 degree fisheye and 60 degree latitude rotation

It can be illustrative to visualise where each part of the fisheye maps to especiallyfor fisheyes greater than 180 degrees. The following image will be used to illustratethis, the image is surrounded by a red frame and the fisheye circle a blue frame. Notethat the area between the blue and red frame can still be considered to be part ofthe fisheye, just with wider angles.

Considering the fisheye circle to be 160, 180, 200, 220 degrees gives the following equirectangular images. Note the light grey surround correspond to angles in theequirectangular that are not mapped.

160 degrees
180 degrees
200 degrees
220 degrees

In addition to equirectangular projectiosn, there are of course a whole range ofother projections that can represent wide fields of view, including the full sphere.One of these is the Hammer projection that represents projects the full 360x180 degreesphere onto a plane while preserving area. While a fisheye can not (usually) fill theequirectangular (or Hammer) domain, two fisheyes at 180 degrees to each other can.An example below from a dual fishey camera.

The corresponding Hammer projection of the two halves jointed together is as follows.

The mathematics is as follows for the reverse transformation, that is, given a pixelin Hammer space what is the corresponding longitude and latitude, these can then be usedto sample the input fisheye for example.If x and y is the pixel position on the Hammer plane (2:1 aspect) and each normalised to range from -sqrt(2) to sqrt(2) then define z as

z = sqrt(1 - x2/4 - y2/4)

then

Microsoft Panorama Stitcher

longitude = 2 atan(xz / (2z2 - 1))
latitude = asin(yz)

The ellipse cropping can be achieved by removing points where

x2 + y2 > 2

Fisheye to (full) panorama

Software: fish2pano

Update December 2016: This function now only creates cylindrical panoramas and fish2sphereonly creates spherical (equirectangular) projections.

The following is a slightly more general version of conversion to a panoramic projection.It creates cylindrical projections, handles different fisheyeorientations but the main difference is it is designed to image into a full 360 projection obviously withparts not covered because of the limited field of view of a fisheye compared to a fullspherical projection.

Example 1: Source fisheye image.

Black refers to the corners of the fisheye image and the grey to the unavailable data,that is, data outside the fisheye rectangle in which the circular fisheye is inscribed.Note that for a wider than 180 degree fisheye the black and grey regions will be correspondingly smaller. The 'x' axis is to the right, the 90 degree rotation heregives the desired result for a forward pointing fisheye. A fisheye pointing straightup or straight down would more normally be transformed with '-x 0'.


fish2pano -a 3 -w 800 -x 90

Cylindrical projection, vertical field 60 degrees and 100 degrees respectively.The vertical extent of the image is, normally, determined correctly given the vertical field of view requested but that can be overruled if desired.


fish2pano -a 3 -w 800 -x 90 -c

fish2pano -a 3 -w 800 -x 90 -c -v 100

Example 2: Source fisheye image

The default settings (no x axis rotation) provide what one expects for an upper hemisphereas per a standard Earth map. Note the apparent distortion towards the north pole, which againis not a strictly distortion but a natural consequence of the mathematics behind the projection.


fish2pano -a 3 -w 800

Cylindrical panorama with a 100 degree vertical field of view, that is, from the equator (0 degreeslatitude) to 100 degrees latitude.


fish2pano -a 3 -w 800 -c -v 100

Panorama Stitcher Online

Fisheye to cube maps

Software: fish2cube

Front facing fisheye example, although note the fisheye can be rotated to any angle withinthe cube.

Input image, a 220 degree fisheye pointing forwards.

Panorama Stitcher App

The resulting cube maps with command line 'fish2cube -w 1024 -s 220 test220.tga'noting that the faces are provided as separate files, they have been manually combined here.

Front facing fisheye example, although note the fisheye can be rotated to any angle withinthe cube.

Input image, a 250 degree fisheye pointing upwards.

Windows Panorama Stitcher

The resulting cube maps with command line 'fish2cube -w 1024 -s 250 -x 90 test250up.tga'.