1Defish0r is a Frei0r plugin that can convert fisheye video to
2rectilinear, and vice versa. It is based on the angular mapping
3functions actually used in fisheye lens design, to get the best
4possible results. It can also be used to correct the slight distortion
5of some wideangle convertors, or to bend the image beyond recognition
6for special effects and light shows.
7
8
9Written by Marko Cebokli, jan 2010 and released under GNU GPL
10
11
12RELEASE NOTES
13
14** jan 2010
15Version 0.1
16"pre-alpha" (throw it out and see what happens... :-)
17There is little or no math checking, so floating point exceptions are
18 rather more the rule than an exception...
19
20I've kept the remapping and interpolation functions in a separate file,
21since they are quite universally useful for any program that does
22geometric transforms on images.
23
24** apr 2010
25Version 0.2
26Added some IFs, to avoid "nan" results from asinf()
27
28
29TODO:
30
31- use gavl for remapping
32- make piece between Little and Big Indians
33
34
35SOME NOTES ABOUT THE PLUGIN
36
37This plugin has quite a few adjustable parameters, but don't be afraid -
38tweaking just the first one ("Amount") will usually bring you quite close to the
39desired result...
40
41
42Multiple Choice Parameters:
43
44Defish0r has some "multiple choice" type parameters. Because the Frei0r
45 API does not support this type of parameters, they are implemented as
46 "double", with the usual 0...1000 range. If there are N choices, this
47 range is simply divided into N subranges, representing the choices.
48 For example, if four options are available, the range 0...250
49 represents the first option, the range 251...500 the second, and so
50 on. Within each range, there is no change, 260 is exactly the same as
51 444 in the above four-option example.
52
53
54Description of the available parameters:
55
56"Amount"
57 Controls the amount of (de)distortion applied to the video. It
58 controls the ratio of fisheye focal length to image half diagonal, but
59 in an nonlinear inverse way, to make the control more "comfortable".
60 It can be adjusted beyond "reasonable" values (which differ between
61 the mapping function types), to produce some looney effects. When
62 exploring this range, and the image disappears, check the scaling,
63 could be that the image became too big or too small to see. For some
64 unreasonable values the image might indeed disappear, when there are
65 math overflows or imaginary results... (types 1 and 2 are more prone
66 to image vanishing). Anyway, when working in the "special effect"
67 range, it is alway worth to try manual scaling.
68
69"DeFish"
70 If checked, the transform direction is from fisheye to rectiliear,
71 when not checked, it is rectilinear to fisheye.
72
73"Type"
74 Selects the fisheye angular mapping function used, among four
75 possibilities:
76 choice range function
77 0 0...250 equidistant
78 1 251...500 ortographic
79 2 501...750 equiarea
80 3 751...1000 stereographic
81 Wikipedia has a nice article about these.
82
83"Scaling"
84 Select among three auto scaling options and manual scale:
85 choice range function
86 0 0...250 scale to fill
87 1 251...500 keep center scale
88 2 501...750 scale to fit
89 3 751...1000 manual scale
90 "Fill" means that no empty borders will be left, but some of the
91 input image will be cropped. "Fit" means that no part of the input
92 image will be cropped, but there will be blank areas at the borders.
93
94"Manual Scale"
95 When "Scaling" is set to option 3 (>751), this control directly
96 affects the image scale, from 1/100 to 100X size. Only has effect when
97 "Scaling" is set to manual!
98
99"Interpolator"
100 Selects among seven different interpolators. This allows one to make
101 a quality/speed tradeoff. In most cases, a higher number means
102 better quality, but slower interpolation. The spline interpolating
103 polynomials are from Helmut Dersch. For realtime use, option 0 is the
104 fastest, in fact it is equal to no interpolation. In most cases
105 bilinear should be good enough, and on a decent machine should still
106 run in real time. Beyond bicubic, the quality gain is marginal for a
107 single resampling. Lanczos takes an eternity!
108 choice range function
109 0 0...142 Nearest neighbor
110 1 143...285 Bilinear
111 2 286...428 Bicubic smooth
112 3 429...571 Bicubic sharp
113 4 572...714 Spline 4x4
114 5 715...857 Spline 6x6
115 6 858...1000 Lanczos 16x16
116
117"Aspect Type"
118 Selects among four pixel aspect ratio presets, and manual:
119 choice range function
120 0 0...200 Square pixels
121 1 201...400 PAL DV 1.067
122 2 401...600 NTSC DV 0.889
123 3 601...800 HDV 1.333
124 4 801...1000 manual variable
125 To get the math right, Defish0r needs to know the pixel aspect
126 ratio. Because I found no way to get the aspect info from the host
127 application, I delegated the responsibility to the user :-)
128
129"Manual aspect"
130 When "Aspect Type" is set to option 4 (>801), this control directly
131 affects the pixel aspect ratio, from 0.5 to 2. Only has effect when
132 "Aspect Type" is set to manual!
133
134
135SOME APPLICATION NOTES
136
1371. Tweaking the parameters for best defish
138
139Take a shot of something like a brick wall or bathroom tiles, that has
140a lot of horizontal and vertical straight lines. Be careful to keep
141the optical axis as perpendicular as possible to the wall (=keep a maximally
142symmetrical image in the viewfinder). Use this
143image to tweak the parameters.
144
145
1462. Some examples of Defish0r abuse
147
148These were tried with PAL DV, in Kdenlive, where the parameters can be
149adjusted between 0 and 1000. These examples work best, when there is
150some interesting action near the center of the image.
151
152For a kind of roundish kaleidoscope, try this:
153Amount=775
154Defish = OFF
155Type = 0
156Scaling = 1000 (manual)
157Manual Scale = 300...400
158
159Another crazy distortion:
160Amount = 921
161Defish = OFF
162Type = 1000
163Scaling = 1000 (manual)
164Manual Scale = 191
165
166For an effect, reminiscent of some scenes from the "2001 Spcae Odyssey" try
167this:
168Amount = 876
169Defish = ON
170Type = 0
171Scaling = 0 (fill)
172