Defish0r is a Frei0r plugin that can convert fisheye video to
rectilinear, and vice versa. It is based on the angular mapping
functions actually used in fisheye lens design, to get the best
possible results. It can also be used to correct the slight distortion
of some wideangle converters, or to bend the image beyond recognition
for special effects and light shows.
Written by Marko Cebokli, jan 2010 and released under GNU GPL
RELEASE NOTES
** jan 2010
Version 0.1
"pre-alpha" (throw it out and see what happens... :-)
There is little or no math checking, so floating point exceptions are
rather more the rule than an exception...
I've kept the remapping and interpolation functions in a separate file,
since they are quite universally useful for any program that does
geometric transforms on images.
** apr 2010
Version 0.2
Added some IFs, to avoid "nan" results from asinf()
TODO:
- use gavl for remapping
- make piece between Little and Big Indians
SOME NOTES ABOUT THE PLUGIN
This plugin has quite a few adjustable parameters, but don't be afraid -
tweaking just the first one ("Amount") will usually bring you quite close to the
desired result...
Multiple Choice Parameters:
Defish0r has some "multiple choice" type parameters. Because the Frei0r
API does not support this type of parameters, they are implemented as
"double", with the usual 0...1000 range. If there are N choices, this
range is simply divided into N subranges, representing the choices.
For example, if four options are available, the range 0...250
represents the first option, the range 251...500 the second, and so
on. Within each range, there is no change, 260 is exactly the same as
444 in the above four-option example.
Description of the available parameters:
"Amount"
Controls the amount of (de)distortion applied to the video. It
controls the ratio of fisheye focal length to image half diagonal, but
in an nonlinear inverse way, to make the control more "comfortable".
It can be adjusted beyond "reasonable" values (which differ between
the mapping function types), to produce some looney effects. When
exploring this range, and the image disappears, check the scaling,
could be that the image became too big or too small to see. For some
unreasonable values the image might indeed disappear, when there are
math overflows or imaginary results... (types 1 and 2 are more prone
to image vanishing). Anyway, when working in the "special effect"
range, it is always worth to try manual scaling.
"DeFish"
If checked, the transform direction is from fisheye to rectiliear,
when not checked, it is rectilinear to fisheye.
"Type"
Selects the fisheye angular mapping function used, among four
possibilities:
choice range function
0 0...250 equidistant
1 251...500 ortographic
2 501...750 equiarea
3 751...1000 stereographic
Wikipedia has a nice article about these.
"Scaling"
Select among three auto scaling options and manual scale:
choice range function
0 0...250 scale to fill
1 251...500 keep center scale
2 501...750 scale to fit
3 751...1000 manual scale
"Fill" means that no empty borders will be left, but some of the
input image will be cropped. "Fit" means that no part of the input
image will be cropped, but there will be blank areas at the borders.
"Manual Scale"
When "Scaling" is set to option 3 (>751), this control directly
affects the image scale, from 1/100 to 100X size. Only has effect when
"Scaling" is set to manual!
"Interpolator"
Selects among seven different interpolators. This allows one to make
a quality/speed tradeoff. In most cases, a higher number means
better quality, but slower interpolation. The spline interpolating
polynomials are from Helmut Dersch. For realtime use, option 0 is the
fastest, in fact it is equal to no interpolation. In most cases
bilinear should be good enough, and on a decent machine should still
run in real time. Beyond bicubic, the quality gain is marginal for a
single resampling. Lanczos takes an eternity!
choice range function
0 0...142 Nearest neighbor
1 143...285 Bilinear
2 286...428 Bicubic smooth
3 429...571 Bicubic sharp
4 572...714 Spline 4x4
5 715...857 Spline 6x6
6 858...1000 Lanczos 16x16
"Aspect Type"
Selects among four pixel aspect ratio presets, and manual:
choice range function
0 0...200 Square pixels
1 201...400 PAL DV 1.067
2 401...600 NTSC DV 0.889
3 601...800 HDV 1.333
4 801...1000 manual variable
To get the math right, Defish0r needs to know the pixel aspect
ratio. Because I found no way to get the aspect info from the host
application, I delegated the responsibility to the user :-)
"Manual aspect"
When "Aspect Type" is set to option 4 (>801), this control directly
affects the pixel aspect ratio, from 0.5 to 2. Only has effect when
"Aspect Type" is set to manual!
SOME APPLICATION NOTES
1. Tweaking the parameters for best defish
Take a shot of something like a brick wall or bathroom tiles, that has
a lot of horizontal and vertical straight lines. Be careful to keep
the optical axis as perpendicular as possible to the wall (=keep a maximally
symmetrical image in the viewfinder). Use this
image to tweak the parameters.
2. Some examples of Defish0r abuse
These were tried with PAL DV, in Kdenlive, where the parameters can be
adjusted between 0 and 1000. These examples work best, when there is
some interesting action near the center of the image.
For a kind of roundish kaleidoscope, try this:
Amount=775
Defish = OFF
Type = 0
Scaling = 1000 (manual)
Manual Scale = 300...400
Another crazy distortion:
Amount = 921
Defish = OFF
Type = 1000
Scaling = 1000 (manual)
Manual Scale = 191
For an effect, reminiscent of some scenes from the "2001 Space Odyssey" try
this:
Amount = 876
Defish = ON
Type = 0
Scaling = 0 (fill)