# FFT3DFilter

## Přehled

autor: Alexander G. Balachnin aka Fizick
verze: 2.1.1
stáhnout: http://avisynth.org.ru/, http://avisynth.org/warpenterprises/
kategorie: Prostorově časové odšumovače
požadavky: YV12 nebo YUY2 Barevné prostředí
licence: GPL

## Úvod

#### FFT3DFilter je 3D frekvenční filtr - silný odšumovač a mírný zostřovač.

### Technické informace

FFT3DFilter používá rychlou metodu Fourierovy transformace (Fast Fourier Transform - FFT) pro zpracování obrazu ve frekvenční oblasti. Je založen na některých pokročilých matematických algoritmech optimální filtrace. Nepracuje lokálně, ale provádí určité delokalizované (blokové) zpracování. V 3D režimu, to vede k efektu podobnému částečné kompenzaci pohybu. Tento filtr může snížit šum bez viditelné ztráty kvality a bez artefaktů, i dokonce při dost silných nastaveních. Může velmi zlepšit kompresi a snížit velikost enkódovaného souboru.
Také má možnost omezeného zostření (limited sharpening) jak bez zesilování šumu, tak i přeostření (haloing).
Fikce? Zkuste ho sami! :)

#### Tedy, je to prostorově časový (3D) filtr, a pracuje následovně:

1. získá aktuální a několik předchozích snímků;
2. rozdělí každý snímek na malé překrývající se bloky;
3. vypočítá frekvenční spektrum okenní 2D FFT transformací každého bloku těchto snímků;
4. použije nějaký filtr na frekvenční spektrum;
5. volitelně zostří obraz (ve 2D frekvenční oblasti) zesilováním některých frekvencí;
6. provede inverzní 2D FFT transformaci vyčištěného spektra pro každý blok;
7. provede okenní sumaci vyčištěných překrytých bloků do výstupního snímku.

Překryté bloky a vážená okna jsou použita pro odvrácení kostkatění (a zvonění hran).
Bloky jsou překryté o nějakou hodnotu v jejich vertikální i horizontální velikosti.
Čím menší překrytí, tím rychlejší zpracování, ale s viditelnějšími mřížkovými artefakty.

Princip překrývání je zobrazen na obrázku.

Jsou využita některá vážená okna analýzy a syntézy pro obdržení efektivního koeficientu signálu gain=1 po sumarizaci bloků.

#### Plugin má několi režimů zpracování ve stadiu filtrace:

- (Parametr bt=1) 2D (prostorový-spatial) Wiener filtr pro spektrální data. Používá data jen aktuálního snímku. Snižuje slabé frekvence (s malým spektrálním výkonem) optimální Wiener filtrací s nějakou zadanou hodnotou šumu. Zostření a odšumění jsou v tomto režimu současné.
- (Parametr bt=2) 3D Wiener filtr pro spektrální data. Přidává třetí rozměr do FFT použitím dat předchozího a aktuálního snímku. Snižuje slabé frekvence (s malým spektrálním výkonem) optimální Wiener filtrací s nějakou zadanou hodnotou šumu.
- (Parametr bt=3) Také 3D Wiener filtr pro spektrální data s daty z předchozího, aktuálního a následujícího snímku.
- (Parametr bt=4) Také 3D Wiener filtr pro spektrální data s daty ze dvou předchozích, aktuálního a následujícího snímku.
- (Parametr bt=5) Také 3D Wiener filtr pro spektrální data s daty ze dvou předchozích, aktuálního a dvou následujících snímků.
- (Parametr bt=0) Časový (temporal) Kalman filtr pro spektrální data. Používá data ze všech předchozích snímků pro získání odhadu vyčištěných dat aktuálního snímku pomocí algoritmu optimálního rekurzivního procesu. Filtr začíná pracovat s malou silou (=1) (stupněm snížení šumu), a pak postupně (po snímcích) zvyšuje sílu, jestli lokální mezisnímková spektrální variace (šum) je malá. Tak může Kalman filtr poskytnout silnější redukci šumu než Wiener filtr. Síla Kalman filtru se omezuje nějakou zadanou hodnotou šumu. Lokální síla (a práce filtru) se resetuje na 1, když lokální variace převýší zadanou prahovou hodnotu (kvůli pohybu, změně scény, atd.). Tedy, výstup Kalman filtru je závislý na historii (na snímku od kterého se začalo filtrovat).

#### Použití šablony šumu

Od v1.5 je možné získat strukturu šumu (model) spektrální analýzou některých prázdných bloků (bez jakýchkoli objektů), a pak redukovat šum stejnou strukturou v celém snímku a v celém klipu. To může být užitečné pro odstranění zrnění filmu (obzvláště amatérského 8 mm) a interference analogových TV nahrávek.

#### Zostřování

Při zostřování (po odšumění) plugin zesiluje frekvence vysokého spektra (prostorové, 2D).
Je zde také jen zostřovací režim, bez odšumění (bt=-1).
Od verze 1.1, jsou použity některé speciální metody omezeného zostřování (limited sharpening) :

- nejslabší frekvence (s malými amplitudami) nejsou zesilovány aby se zabránilo zvyšování šumu;
- nejsilnější frekvence (s velkými amplitudami) nejsou zesilovány aby se zabránilo přeostření a tzv. haloing.

Zostřovací síla je maximální pro frekvence s amplitudami ve středním rozsahu. Samozřejmě můžete ovládat obě tyto meze i obecnou zostřovací sílu.

Od v.1.7, je pro zostření použit Gaussův filtr vysokých frekvencí s proměnnou frekvencí střihu.

Od v.1.9, má plugin speciální možnost dehalo pro snížení silných frekvencí, měl by být použit pro prostorové adaptivní změkčení přeostřených obrazů (odstranění halo). Tento režim může být kombinován s odšuměním a zostřením.

### Syntaxe

`FFT3DFilter`(clip, float "sigma", float "beta", int "plane", int "bw", int "bh", int "bt", int "ow", int "oh", float "kratio", float "sharpen", float "scutoff", float "svr", float "smin", float "smax", bool "measure", bool "interlaced", int "wintype", int "pframe", int "px", int "py", bool "pshow", float "pcutoff", float "pfactor", float "sigma2", float "sigma3", float "sigma4", float "degrid", float "dehalo", float "hr", float "ht", int "ncpu")

Všechny parametry jsou jmenné.

### Parametry funkce:

první parametr - vstupní klip

sigma - zadaná hodnota šumu pro všechny (nebo nejvyšší) frekvence (desetinná>0, výchozí=2.0)
beta - hranice šumu (desetinná>=1.0, výchozí=1.0 pro žádný zbytek šumu):
ovládá množství šumu zbývajícího po použití Wiener filtru, takže maximální potlačení šumu filtrem = (beta-1)/beta.
plane - zpracovávaná barevná plocha: 0 - jas(Y), 1 - barevnost U, 2 - barevnost V,
3 - plochy barevnosti U a V, 4 - jak jas tak barevnost (výchozí = 0)
bw - šířka bloku (celočíselná, výchozí = 48 od v.1.2)
bh - výška bloku (celočíselná, výchozí = 48 od v.1.2)
bt - časový rozměr bloku, počet snímků (-1, 0, 1, 2 nebo 3, výchozí = 3):
0 - všechny předchozí snímky (zapíná režim Kalman filtru);
1 - jen aktuální snímek (prostorový 2D Wiener filtr);
2 - předchozí a aktuální snímek (3D Wiener filtr);
3 - předchozí, aktuální a následující snímek (3D Wiener filtr)
4 - dva předchozí, aktuální a následující snímek (3D Wiener filtr)
5 - dva předchozí, aktuální a dva následující snímky (3D Wiener filtr)
-1 - jen zostření (2D);
ow - šířka překrytí (výchozí=bw/3 od v.1.2)
oh - výška překrytí (výchozí=bh/3 od v.1.2)
kratio - poměr prahové hodnoty ku sigma pro resetování Kalman filtru (default = 2.0):
prahová hodnota variace = sigma*kratio, dobré hodnoty jsou od 1.5 do 3.0;
sharpen - síla zostřaní (výchozí=0 - nezostřovat)
dobré hodnoty 0.3 až 1.0 (záporné hodnoty vedou k obrácenému efektu)
scutoff - frekvence střihu zostřování, relativní k maximální (výchozí=0.3)
svr - poměr vertikálního zostřování (a dehalo) k horizontálnímu (výchozí=1.0 - stejně jako horizontální, 0 - bez vertikálního zostřování)
smin - spodní hranice (přibližná hranice šumu) pro stádium zostřování (výchozí=4.0)
smax - horní hranice (přibližná hranice přeostření) pro stádium zostřování (výchozí=20.0)
measure - vybírá optimální (nejrychlejší) FFT metodu měřením rychlosti (s delším inicializačním časem)
místo jednoduchého odhadu (výchozí=true od v.0.9.2)
interlaced - rozděluje zpracování polí (výchozí=false)
wintype - typ vážících oken (výchozí=0):
0 - stejná okna analýzy a synteze polo-kosina, používali se ve všech verzích před 1.4;
1 - střed mezi 0 a 2;
2 - rovinné okno analýzy, okno syntézy zvýšeného kosina (Hanning).
pframe - číslo snímku s modelem šumu (výchozí=false)
px - horizontální X pozice bloku modelu šumu (výchozí=0)
py - vertikální Y pozice bloku modelu šumu (výchozí=0)
pokud px=py=0, pak je modelový blok definován automaticky s minimální sílou spektra.
pshow - zobrazí modelový blok šumu a jeho vlastnosti (výchozí=false)
pcutoff - frekvence střihu modelu šumu (relativní k maximální) (výchozí=0.1)
pfactor - síla odšumění modelu šumu (0 až 1.0, výchozí=0, tato metoda vypnuta)
sigma2 - zadaná hodnota šumu ve druhé úrovni měřítka frekvencí (desetinná>0, výchozí=sigma)
sigma3 - zadaná hodnota šumu ve třetí úrovni měřítka frekvencí (desetinná>0, výchozí=sigma)
sigma4 - zadaná hodnota šumu na nejnižších frekvencích (desetinná>0, výchozí=sigma)
degrid - stupeň kompenzace vážícího okna pro snížení mřížky (desetinná>0, výchozí=1.0)
dehalo - síla odstranění halo (desetinná>0, výchozí=0.0)
hr - přibližný radius halo (desetinná>0, výchozí=2.0)
ht - přibližná prahová hodnota halo (desetinná>0, výchozí=50.0)
ncpu - maximální počet vláken CPU použitých pro výpočet FFT (celočíselný>0, výchozí=1)

Nejdůležitějším parametrem je zadaná hodnota šumu sigma. Musíte použít rozumnou hodnotu založenou na dřívější informaci o aktuálním klipu.
Typická hodnota pro digitální zdroje je asi 1.5 až 2.5, a asi 3 a výše pro analogové videonahrávky.
Dobrá hodnota velikosti překrytí je asi čtvrt až půl velikosti bloku. Polovina (ow=bw/2, oh=bh/2) je nejlepší, ale pomalejší.
Dobré hodnoty velikosti bloku jsou asi 32 až 64.

Filtr může vytvářet nějaké mřížkové artefakty u velkých sigma a malých bw, bh, ow, oh nebo malých relativních rozměrech překrytí, obzvláště se zapnutým zostřováním.
Filtr může vytvářet duchy u velkých sigma (a kratio) pro 3D režimy.

Vážící okna wintype=0 může vytvářet horší mřížkové artefakty, okna typu wintype=2 nevytváří mřížkové artefakty, ale mohou vytvářet nějaké zvonění, wintype=1 je prostřední případ.

Doporučuji používat kompenzaci okenního vážení s degrid=1 (od verze 1.8), to zlepšuje kvalitu odšumění a snižuje mřížkové artefakty, obzvláště pro 2D.

Zostření povede k horší kompresi klipu.

Pro použití metody modelu šumu namísto obyčejné (slepé) metody musíte:
Nejdříve zapnout zobrazovací režim pshow=true, a nastavit nějakou nenulovou hodnotu pfactor=1.0.
Pak zvolte číslo snímku a nějakou pozici bloku, aby zobrazovaný blok neobsahoval žádné objekty kromě modelu typického šumu.
Vypněte zobrazovací režim pshow=false,
a nastavte sílu redukce šumu, doporučená hodnota pfactor= 0.5 až 1.0.
Nejlepší okenní typ pro tento případ je wintype=2.
Parametry sigma a beta nejsou v této metodě odšumění použity, ale můžete použít tuto metodu v zobrazovacím režimu pshow=true pro odhadnutí hodnoty sigma pro obyčejnou metodu odšumění (není to přísně ta samá, ale podobná hodnota).

Je zde také kombinovaná metoda, kdy můžete přímo nastavit různé hodnoty šumu sigma pro nejvyšší a sigma2, sigma3, sigma4 pro nižší frekvence. Koeficienty modelu budou vnitřně vytvořeny z těchto hodnot sigma interpolací. Pro tuto metodu nastavte pfactor=0 (vnitřně to bude =1).

### Zvláštnosti a omezení

1. Filtry pracují jen v YV12 nebo YUY2 barevných formátech.
2. Může zpracovávat jen zadanou barevnou plochu (Y, U nebo V). Od v1.8.4 je možné zpracovávat několik (všechny) barevné plochy.
3. Od v1.3 pracuje s jak progresivními tak s prokládanými klipy.
4. Testováno s Avisynthem v2.55, v2.56, v2.57.
5. Filtr používá rychlou externí FFTW knihovnu verze 3 (http://www.fftw.org)
   jako Windows binární DLL (kompilovanou gcc pod MinGW Alessiem Massarem), která podporuje více vláken a má AMD K7 (3dNow!) podporu navíc k SSE/SSE2.
   Můžete ji stáhnout z ftp://ftp.fftw.org/pub/fftw/fftw3win32mingw.zip
   MUSÍTE vložit soubor FFTW3.DLL z tohoto balíku (ne fft3dfilter.dll) do nějaké složky v systémem prohlížené cestě (například, C:\WINNT\SYSTEM32).
   Filtr bez ní NEPRACUJE!
6. Knihovna FFTW pracuje nejefektivněji pro pole jejichž rozměry (bw, bh) mohou být rozloženy do malých prvočísel 2, 3, 5, a 7 (a jednou 11, 13), a jinak používá pomalejší rutiny pro obecné účely.
7. První verze byly skutečně pooomalé! Ale novější verze jsou už prostě jen pomalé :-).
   Je vylepšen algoritmus i instrukce assembleru 3DNow! a pro některé režimy jsou použity SSE instrukce
8. Algoritmus je rychlostně optimalizován jen pro dopředný sekvenční přístup ke snímkům.
9. Zostřovací metoda je experimentální, nicméně je docela dobrá od v1.1 (a v1.7).
10. Metoda modelu šumu je také experimentální.
11. Možnost degrid není implementována pro Kalman filtr.
12. Pro zašumělé video je užitečné použít mediánové předfiltrování (například DeGrainMedian) před FFT3Dfilter.
13. Vícevláknový režim ncpu>1 je téměř netestovaný (já nemám core duo), zkuste použít ncpu=2 pokud ho vy máte.

### Jednoduché příklady skriptů

#### Pro odšumění jasové plochy progresivního nebo na polích založeného (rozloženého na pole) klipu:

    Avisource("vstup.avi")
    loadplugin("c:\plugins\fft3dfilter.dll")
    FFT3DFilter(sigma=3)

Samozřejmě musíte nahradit "c:\plugins" vaší cestou ke složce s pluginy (a také nastavit cestu k vašemu videu :). Můžete přeskočit příkaz LoadPlugin pokud vložíte soubor fft3dfilter.dll do autonačítací složky pluginů (C:\Program Files\Avisynth 2.5\plugins).

#### Jen zostření:

    Avisource("vstup.avi")
    loadplugin("fft3dfilter.dll")
    FFT3DFilter(bt=-1, sharpen=0.7)

#### Odšumění a mírné zostření prokládaného klipu:

    Avisource("vstup.avi")
    loadplugin("fft3dfilter.dll")
    FFT3DFilter(sigma=2, sharpen=0.3, interlaced=true)

#### Jakési "nejlepší nastavení", pomalé zpracování

    Avisource("vstup.avi")
    loadplugin("fft3dfilter.dll")
    fft3dfilter(sigma=1.5, bt=5, bw=32, bh=32, ow=16, oh=16, sharpen=0.4)

#### Odšumění všech barevných ploch (jak jasu tak barevnosti)

Poznámka: Rychlost zpracování se hodně sníží, takže můžete zvážit jiné (podobné a rychlejší) filtry používající odšumění barevnosti (`CNR2`, `DeGrainMedian`, atd).

#### Odšumění všech barevných ploch se stejným nastavením

    Avisource("vstup.avi")
    loadplugin("fft3dfilter.dll")
    fft3dfilter(sigma=2, plane=4)

#### Odšumění jasu a barevnosti s různým nastavením

    Avisource("vstup.avi")
    loadplugin("fft3dfilter.dll")
    fft3dfilter(sigma=1.5, plane=0)
    fft3dfilter(sigma=3, plane=3)

#### Jiný způsob jak odstranit šum z barevných ploch (skript od AI)

Ve starých verzích bylo důležité jestli jste používali kompenzaci pohybu

    Avisource("vstup.avi")
    loadplugin("fft3dfilter.dll")
    YToUV(fft3dfilter(sigma=3, plane=1).UToY,\
    fft3dfilter(sigma=3, plane=2).VToY,\
    fft3dfilter(sigma=2, plane=0))

#### Snížení existujícího horizontálního halo efektu

    Avisource("vstup.avi")
    loadplugin("fft3dfilter.dll")
    fft3dfilter(bt=-1, plane=0, dehalo=1.0, hr=2.0, ht=50, svr=0)

### Doplňující informace

Algoritmus Wiener filtru je zložen na 3D IIR/3D Frequency Domain Filter z:
MOTION PICTURE RESTORATION. by Anil Christopher Kokaram. Ph.D. Thesis. May 1993.
http://www.mee.tcd.ie/~ack/papers/a4ackphd.ps.gz v postscript formátu (použijte GSview s Ghostscript pro přečtení).
O Wiener a Kalman filtrech hledejte více informací ve speciální literatuře nebo na Googlu.

Diskuze k filtru je na DOOM9 Avisynth fóru, ve vlákně "New very slow FFT denoiser:"
http://forum.doom9.org/showthread.php?t=85790

Existuje také plugin `FFT3DGPU` (od tsp) s podobným algoritmem, ale využívající procesory moderních grafických karet pro výpočet FFT.
Tsp portoval mnoho funkcí z fft3dfilter. Viz http://forum.doom9.org/showthread.php?t=89941.

### Licence

Tento program je svobodný software; můžete ho dále rozšiřovat a/nebo upravovat
ho za podmínek GNU General Public License version 2 publikované
Free Software Foundation.
Tento program je šířen v naději, že bude užitečný,
ale BEZ JAKÉKOLI ZÁRUKY; dokonce bez předpokládané záruky
OBCHODOVATELNOSTI nebo POUŽITÍ PRO KONKRÉTNÍ ÚČELY. Viz
GNU General Public License pro více podrobností.
Spolu s tímto programem by jste měli obdržet kopii GNU General
Public License; pokud ne, napište do Free Software Foundation.
Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Dokumentace je šířena pod CreativeCommons BY-SA 3.0 license.

Zvažte prosím malou dotaci.

### Změny verzí:

- Version 0.1, November 23, 2004 - initial experimental.
- Version 0.2, December 3, 2004 - added beta parameter (noise margin).
- Version 0.3, December 21, 2004 - added block temporal size parameter bt (was fixed =3 internally).
- Version 0.4, January 16, 2005 - optimized algorithm for speed for bt=2 (now default),
  mode bt=3 is temporary disabled,
  changed default bw=bh=32,
  filtered region now is centered.
- Version 0.5, January 28, 2005 - added YUY2 support.
- Version 0.6, January 29, 2005 - added Kalman filter mode for bt=0, and ratio parameter
- Version 0.7, January 30, 2005 - re-enabled Wiener filter mode with 3 frames (bt=3);
  first and last frame in Wiener 3D mode now filtered (as 2D)
- Version 0.8, February 5, 2005 - added experimental sharpen option and bt=-1
- Version 0.8.1, February 6, 2005 - skip sharpening of the lowest frequencies to prevent parasitic lines near borders
- Version 0.8.2, February 15, 2005 - added internal buffer to process whole frame (borders included) for any bw, bh (a little slower)
- Version 0.8.3, March 16, 2005 - fixed sharpen mode (bt=-1) for YUY2
- Version 0.8.4, April 3, 2005 - (not public) - delayed FFTW3.DLL loading
- Version 0.9, April 4, 2005 - variable overlapping size ow, oh for more fast processing,
  half overlapping ow=bw/4, oh=bh/4 is now default, while full overlapping ow=bw/2, oh=bh/2 was used in all older versions.
- Version 0.9.1, April 7, 2005 - some assembler 3DNow! speed optimization for mode bt=3.
- Version 0.9.2, April 10, 2005 - some assembler 3DNow! speed optimization for mode bt=0,
  option measure=true is now default as more fast.
- Version 0.9.3 - April 24,2005 - fixed bug for bt=2 with 3DNow! (thanks to kxproject for report);
  mode bt=3 now default;
  sharpen mode now is horizontal only and modified (still experimental)
- Version 1.0 - June 27, 2005 - improved frame edges processing (by padding);
  added svr parameter to control vertical sharpening
- Version 1.0.1 - July 05, 2005 - fixed bug for chroma planes for YUY2 (introduced in v.1.0)
- Version 1.1 - July 8, 2005 - improved sharpening method to prevent grid artifactes and to limit sharpening (added parameters smin, smax);
  renamed parameter ratio to kratio.
- Version 1.2 - July 12, 2005 - changed default block sizes bw=bh=48 and overlap sizes ow=bw/3, oh=bh/3 to finally prevent grid artifactes in sharpen mode (but speed is decreased).
- Version 1.3 - July 20, 2005 - added interlaced parameter for interlaced video processing.
- Version 1.3.1 - July 21, 2005 - fixed bug for YUY2 interlaced.
- Version 1.4 - July 23, 2005 - corrected neutral level for chroma processing,
  changed weighting window type with new wintype parameter
- Version 1.5 - July 26, 2005 - added noise pattern method and its parameters pframe, px, py, pshow, pcutoff, pfactor
- Version 1.5.1 - July 29, 2005 - fixed bug with pshow
- Version 1.5.2 - July 31, 2005 - fixed bug with Kalman mode (bt=0) for Athlon (introduced in v1.5)
- Version 1.6 - August 03, 2005 - added mode bt=4; added optimized SSE version for bt=2,3; added sigma2,sigma3,sigma4 parameters for composite method.
- Version 1.7 - August 29, 2005 - changed sharpening to Gaussian filter with new parameter scutoff;
  added SSE version for sharpen mode and pattern modes bt=2,3 ;
  restuctured and released code under GNU GPL v.2.
- Version 1.8 - October 3, 2005 - improved internal FFT cache; added degrid=1.0 parameter as default; changed default wintype=0.
- Version 1.8.1 - October 26, 2005 - fixed bug with sharpen>0 AND degrid>0 for bt not equal 1. (Thanks to Wull for report).
- Version 1.8.2 - 04 November 2005 - really set default degrid=1.0 (was = 0 accidentally).
- Version 1.8.3 - 28 November 2005 - fixed bug with first frame for Kalman YV12 (thanks to tsp).
- Version 1.8.4 - 29 November 2005 - added multiplane modes plane=3,4.
- Version 1.8.5 - 4 December 2005 - fixed bug with memory leakage (thanks to tsp).
- Version 1.9 - 25 April 2006 - added dehalo options; corrected sharpen mode; re-enabled SSE optimization for degrid=0; added SSE optimization for bt=3,-1 with degrid>0 (faster by 15%)
- Version 1.9.1 - 10 May 2006 - added SSE optimization for bt=4 with degrid>0 (faster by 30%).
- Version 1.9.2 - 11 september 2006 - changed default bw=bh=32; added mode bt=5
- Version 2.0.0 - November 29, 2006 - added experimental internal motion compensation mode; window reorganized; internal multithread support (Core duo, trio, quadro et cetera)
- Version 2.1.0 - January 17, 2007 - removed (temporary ?) experimental internal motion compensation mode.
- Version 2.1.1 - February 20, 2007 - fixed bug with bw not mod 4 (restored v1.9.2 method, thanks to JKinG for report).

### Stáhnout FFT3DFilter verze 2.1.1

`$English Date: 2007/02/20 $`

`Český překlad:18.4.2009`