# MVTools

## Abstrato

autor: Manao
versão: 0.9.5
download: http:/ /jourdan.madism.org/~manao/
categoria: Miscelânea de Plugins
requisitos: YV12 Colorspace

## Tabela de Conteúdos

- I) Sobre MVTools
- II) Descrições das Funções
- III) Exemplos
- IV) Retratação (não salte essa parte, mas eu não forço a aprender isto)
- V) Revisões

## I) Sobre MVTools

Coleção de filtros (Blur, ConvertFPS, Denoise, Interpolate, Mask e outros) que usam vetores de movimento gerados por este plugin.

## II) Descrições das Funções

### Parâmetros Comuns

Os filtros que usam vetores de movimento têm parâmetros comuns. Eles permitem fixar os percentuais da detecção de mudança de cena, por exemplo. Além disso, os filtros podem precisar de um ou dois fluxos de vetores de movimento. Quando dois são necessários, um é para trás (obtido por MVAnalyse(isb = true)) e o outro é para frente (MVAnalyse(isb = false)). Por convenção, o para trás tem que ser dado primeiro.

mvsbw : o vetor de movimento para trás.

mvsfw : o vetor de movimento para frente

int thSCD1 : percentual que decide se um bloco mudou entre o quadro anterior e o atual. Quando um bloco muda, significa-me que estimação de movimento para ele não é relevante. Acontece por exemplo em mudanças de cena. Assim é um dos percentuais usados para afinar o motor de detecção de mudança de cena. O padrão é 300. Elevando-o, abaixará o número de blocos detectados como mudados.

int thSCD2 : percentual que fixa quantos blocos têm que mudar para o quadro ser considerado como uma mudança de cena. Varia de 0 a 255, 0 significa 0%, 255 significa 100%. O padrão é 130 (que significa 51%).

### MVAnalyse

`MVAnalyse` (clip, int "bw", int "bh", int "pel", int "lv", int "fth", int "sadt", int "mpt", int "st", int "stp", bool "isb", int "lambda")

bw, bh : Elas são a largura e a altura de um bloco. O valor pode ser só 4 ou 8. Blocos maiores são menos sensíveis a ruídos, são mais rápidos, mas também menos precisos. O padrão é 8 para ambos.

pel : é a precisão da estimação de movimento. 1significa uma precisão para o píxel. 2 significa uma precisão para meio píxel, 4 para um quarto de píxel e assim por diante. O valor só pode ser 1, 2, 4 ou 8 (além de 8, é imprestável e desperdiça muita memória). Padrão: 1. Para o momento, é o único valor possível.

lv : é o número de níveis não usados na análise hierárquica feita enquanto procura vetores de movimento. O mais baixo é o melhor. Só é mantido variável para propósitos de estudo. Padrão: 0.

fth : Não usado mais, tornou-se inútil pelo lambda.

sadt : Não usado mais, tornado inútil pelo lambda e o ganho de velocidade.

st, stp : st decide o tipo de procura, e stp é uma colocação para esta procura:

- st = 0 : 'OneTimeSearch'. stp é o passo entre cada vetor tentado (se stp for superior a 1, o passo será refinado progressivamente). É a procura padrão, com stp = 1.
- st = 1 : 'NStepSearch'. N é fixo por stp. É o mais conhecido algoritmo de procura MV.
- st = 2 : Procura logarítmica, também chamada Diamond Search. stp é a procura de passo inicial, lá novamente, é progressivamente refinada.
- st = 3 : Procura exaustiva, stp é o radius. É lento, mas dá os melhores resultados, SADwise.

isb : permite escolher entre uma procura para frente (entre o quadro atual e o prévio) e um para trás (entre o quadro atual e o seguinte). isb = false significa procura à frente.

lambda : fixe a coerência do campo de vetores. Quanto mais alto, mais coerente. Porém, se fixo muito alto, alguns vetores de movimento 'true' podem ser perdidos. Padrão é 0, mas valores ao redor de 2000 são fortemente recomendados e serão padrões no próximo lançamento.

### MVBlur

`MVBlur` (clip, clip mvsbw, clip mvsfw, int "nb", float "rl", int "fbw", string "wf")

Permite criar um movimento de borrar. O movimento é criado interpolando quadros entre o atual, os próximos e os prévios e então faz um peso significando estas interpolações.

nb decide quantas interpolações são feitas. A maior, a melhor e a mais lenta. rl é equivalente à velocidade do obturador de uma câmera. A mais alta, mais forte o movimento de borrar. A unidade é em fps. fbw permite aumentar o tamanho dos blocos que são movidos ao longo dos vetores de movimento. Por exemplo fbw = 2 aumentará o bloco por uma margem de 2 píxeis. Isto permite menos artefatos, mas conduz a um movimento de borrar ligeiramente menos impreciso (será menos direcional). Finalmente, wf controla o peso das interpolações. Várias strings são possíveis aqui:

- wf = "uniform" : Pesagem uniforme (todos os pesos são iguais a 1).
- wf = "ramp" : o peso é proporcional ao tempo entre a interpolação e o quadro atual.
- wf = "revramp" : é o contrário.
- wf = "hat" : começa com uma ramp e termina como uma revramp.
- else : é uma revramp.

Padrões são: nb = 10, rl = 0.5, fbw = 2 e wf = "uniform".

### MVCompensate

`MVCompensate` (clip, clip vectors)

Faz uma compensação total do movimento do quadro. Significa que os blocos apontados por MV no quadro prévio (ou seguinte, depende da colocação de MVAnalyse) será movido ao longo dos vetores para chegar aos seus lugares no quadro atual.

Difere de filtros como MVinterpolate porque aqui, a reconstrução está completa (significando por que os blocos uma vez movidos não estão se sobrepondo e cobre a figura inteira).

Para o momento, não move o croma (porque precisa de um algoritmo de interpolação de espaço para fazer isso).

### MVConvertFPS

`MVConvertFPS` (clip, clip mvbw, clip mvfw, int "nb", float "rl", int "fbw", int "sbw", int "rbw", int "bvt" [, int num, int den], float "fps", string "wf")

Muda o framerate do clipe, sem mudar seu comprimento. Como o MVBlur, nb é o número de quadros construído para criar um quadro interpolado. rl é a velocidade do obturador da câmera e wf é a função de normalização. fbw, sbw e rbw permitem aumentar o tamanho dos blocos movidos. bvt é um percentual que decide se um vetor de movimento é válido ou não. O valor padrão torna todos os vetores válidos. num e den são o numerador e o denominador do novo framerate. Você também pode dar este número usando os parâmetros fps.

Padrões são: nb = 1, rl = 0, fbw = 4, sbw = 0, rbw = 0, bvt = 35000 e wf = "uniform".

### MVDenoise

`MVDenoise` (clip, clip mvbw, clip mvfw, int "thT", int "sadT")

Faz um denoising (remoção de ruídos) temporal básico com compensação de movimento. Os quadros prévios e seguintes são movimento compensado e então fundidos no quadro atual. Os dois percentuais são usados para prevenir artefatos.

O primeiro, thT, decide se o píxel que vem do quadro prévio ou seguinte tem que ser levado em conta. Se este píxel diferir mais que o do thT do quadro atual, não é usado.

O segundo, sadT, decide se o bloco mudou ou não (mesmo princípio thSCD1). Se mudou, o píxel não é fundido com o do quadro prévio ou seguinte.

Padrões são: thT = 10 e sadT = 160.

Eu diria (sem testar muito) que:

- thT = 5-10, sadt = 100-200 : denoising fraco
- thT = 10-15, sadt = 200-300 : denoising mediano
- thT = 15-25, sadt = 300-500 : denoising forte

### MVInterpolate

`MVInterpolate` (clip, clip mvbw, clip mvfw, int "nb", float "bl", float "el", int "fbw", int "sbw", int "rbw", int "bvt", string "wf")

Permite trocar temporariamente o vídeo de um número não inteiro de quadros, entre 0.0 e 1.0. Trabalha do mesmo modo que MVBlur e MVConvertFPS e significa que nb, fbw, sbw, rbw, bvt e wf trabalham do mesmo jeito. bl e el definem o começo e o fim da interpolação. Se bl for diferente de el, o quadro criado fica ligeiramente borrado. A interpolação é feita entre o quadro atual e o prévio.

Padrões são: nb = 5, bl = 0.4, el = 0.6, fbw = 4, sbw = 0, rbw = 0, bvt = 35000 e wf = "uniform".

### MVMask

`MVMask` (clip, clip vectors, int "ml", float "gamma")

Cria uma máscara de movimento do comprimento dos seus vetores. Constrói uma máscara melhor que MotionMask (MaskTools) porque os vetores de movimento são muito mais confiáveis que o algoritmo de MotionMask.

A máscara só é produzida no plano luma. 0 significa nenhum movimento (o comprimento do vetor de movimento é nulo), considerando que 255 significa movimento máximo e é definido por ml. Quando o comprimento do vetor é superior ou iguala a ml, o valor produzido é 255. gama é usada para definir a relação comprimento - valor. gama = 1.0 indica uma relação linear, enquanto que gama = 2.0 dá uma relação quadrática.

Padrões são: ml = 100 e gamma = 1.0.

### MVShow

`MVShow` (clip, clip vectors, int "scale", int "sil", int "tol', bool "showsad")

Exibe os vetores de movimento. scale permite aumentar os vetores de movimento, para ganhar em precisão (quando pel > 1 e scale = 1, você não pode ver uma variação com menos de um píxel). sil permite ver um nível diferente de análise (ao procurar vetores de movimento, uma análise hierárquica é feita e pode ser interessante ver o que acontece a níveis mais altos). tol é um percentual de tolerância. Se a deformação induzida pelo vetor de movimento está acima de tol o vetor não é mostrado. Finalmente, showsad permite mostrar o significado SAD depois de compensar a imagem.

Padrões são: scale = 1, sil = 0, tol = 20000 e showsad = false (que exibe todos os vetores).

## III) Exemplos

Mostrar os vetores de movimento (para frente):

    vectors = source.MVAnalyse(isb = false)
    return source.MVShow(vectors)

Mostrar para trás:

    vectors = source.MVAnalyse(isb = true)
    return source.MVShow(vectors)

Para u sar MVMask:

    vectors = source.MVAnalyse(isb = false)
    return source.MVMask(vectors)

Para u sar MVBlur :

    vectorsfw = source.MVAnalyse(isb = false)
    vectorsbw = source.MVAnalyse(isb = true)
    return source.MVBlur(vectorsbw, vectorsfw)

É o mesmo para `MVInterpolate`, `MVDenoise` e `MVConvertFPS`.

Para tirar ruídos:

    backward_vectors = source.MVAnalyse(isb = true, lambda = 2000)
    forward_vectors = source.MVAnalyse(isb = false, lambda = 2000)
    return source.MVDenoise(backward_vectors, forward_vectors, tht = 10, sadt = 300)

Um muito lento, mas também muito bom borrador de movimento:

    # Assumindo material de 25 fps. Trabalha muito bem para meu material de CG.
    vec_back = source.MVAnalyse(fth=30, isb=true)
    vec_forw = source.MVAnalyse(fth=30, isb=false)
    MVConvertFPS(last, vec_back, vec_forw, fps=100, fbw=2, thSCD2=255, thSCD1=200)
    TemporalSoften(2, 255, 255, 0, 2)
    SelectEvery(4,0)

Conversão de movimento compensado 60i a 24p:

    function KernelBob(clip a, int ord)
    {
      f = a.KernelDeint(order=ord)
      e = a.SeparateFields.Trim(1,0).Weave().KernelDeint(order=1-ord)
      Interleave(f,e)
    }

    function MVConvert60ito24p(clip x, int "mode")
    {
    mode = default(mode, 2)
    mbl = 0.1

    vectorsforward = x.MVAnalyse(isb = false)
    vectorsbackward = x.MVAnalyse(isb = true)

    y = x.MVInterpolate(vectorsbackward, vectorsforward, nb = 4, bl = 0.5 - mbl, el = 0.5 + mbl, wf = "hat")

    Interleave(y, x)
    mode0 = SelectEvery(5, 2)
    mode1 = Overlay(SelectEvery(5,3),SelectEvery(5,2),opacity=0.5)
    mode2 = Overlay(Overlay(SelectEvery(5,1),SelectEvery(5,3),opacity=0.5),SelectEve
    ry(5,2),opacity=0.3)
    mode3 = Overlay(Overlay(SelectEvery(5,0),SelectEvery(5,3),opacity=0.5),Overlay(S
    electEvery(5,1),SelectEvery(5,2),opacity=0.5),opacity=0.5)

    (mode==0) ? mode0 : (mode==1) ? mode1 : (mode==2) ? mode2 : mode3
    }

    x = source.KernelBob(ord=0)  # ou outro bobber
    MVConvert60ito24p(x)

## IV) Retratação

Este plugin é liberado sob licença GPL. Você tem que aceitar as condições do 'Copying.txt' antes de usar o plugin ou seu código fonte.

## V) Revisões

0.9.5

- Huge rewritting of the core engine. Vectors are now searched with a precision up to the pixel ( because no other filters can use yet more precise vectors, except MVShow ). The search engine is now fast ( which doesn't mean necessarily that the filters which use it are fast )
- A new parameter for MVAnalyse : lambda. See the documentation of the filter to see how it works
- MVDenoise works better.

0.9.4

- Vectors can be saved to a file. In order to do so, add the parameter filename="C:\foo.bar" to the filter MVAnalyse. If the file doesn't exist, vectors will be saved into it. If it exists, vectors will be read from it. But, be warned :
  - The file for a whole movie will be around 500 MB
  - Saving / reading from a file need for the moment a linear access to the frames, so it has to be used only when encoding the movie, not when doing random access in it.
  - The speed gain is not as great as one may hope, because SADs can't be saved ( it would take too much space ) and so have to be recomputed.
- The filter MVDenoise now works on 5 frames, and its parameters are now "thT" and "sadT" ( have a look in the documentation to see how they work ). It works nice ( very good for heavy denoising )
- The scene change detection thresholds have slightly changed. Now, a block has changed if its SAD it over thSCD1. The default for thSCD1 is 300, and for thSCD2 it is 130. It orks well ( better than the previous SCD engine ).

0.9.3

- Last cleanings in the search of the motion vectors. It should be slightly faster
- More search parameters can be set by the user, especially the search algorithm. See the documentation
- Server / client implemented. You now first have to use MVAnalyse, and then the filter you want. Look at the documentation and at the examples I'll give alter.
- MVCompensate is separated from MVShow ( it's more logic that way ). For the moment, it doesn't move the chroma ( same behavior as MVShow in the latest releases )
- Some cleaning in MVBlur / MVInterpolate / MVConvertFPS, but still some work to do. Now, MVBlur blurs around the frame, not between the frame and the previous one.
- Half of the work is done for writing vectors to a file. But the resulting file will be large ( around 500 MB - 1 GB I guess ).
- MVDenoise is slightly faster ( at least it should )
- Copies are optimized inside the filter, thanks to avisynth's copy functions.
- MVShow can display the mean SAD of the compensation ( using showsad = true )

0.9.2.1

- MVInterpolate makes its come back.
- MVConvertFPS should work on the last few frames of the clip

0.9.2

- MVInterpolate doesn't exist anymore.
- MVBlur and MVConvertFPS have been improved. They also have got new parameters, have a look at the documentation.
- MVShow gets back its compensate mode ( MVShow(cm = true) )

$Date: 2006/03/26 18:11:53 $`Portuguese translation by RoLon`