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 convertors, 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 alway 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 Spcae Odyssey" try
this:
Amount = 876
Defish = ON
Type = 0
Scaling = 0 (fill)
