# DePan

## Abstrato

autor: Alexander G. Balakhnin aka Fizick
versão: 0.9
download: http://bag.hotmail.ru/
categoria: Miscelânea de Plugins
requisitos: YV12 Colorspace

As ferramentas DePan estimam movimento global (panorama) em quadros e faz compensação de movimento global total ou parcial.

As ferramentas de DePan podem ser usadas para:

- compensação de movimento global para denoising (remoção de ruídos) temporal forte e restauração de clipe (filme).
- recriar quadros danificados pela interpolação de movimento,
- criar séries de quadros intermediários para mudança de freqüência (fps).
- fazer a estabilização do movimento parcial;

O plugin de DePan tem que substituir meu GenMotion C-plugin experimental (que usa dados de movimento do arquivo log de plugin Deshaker do VirtualDub).

O DePan trabalha em um passe, mas consiste em parte de servidor (função) e uma ou mais partes clientes (funções ou suas instâncias). A função do servidor estima dados de movimento de quadros e os dá às funções de cliente em inquisição. A versão atual do DePan usa um clipe de serviço especial como o recipiente de dados de movimento.

### Funções do plugin DePan

DePanEstimate (servidor) - estima dados de movimento de quadros globais e grava-os no clipe de serviço especial
DePan (cliente) - faz compensação de movimento global total ou parcial
DePanInterleave (cliente) - gera clipe de movimento longo compensado intercalado
DePanStabilize (cliente) - estabiliza o movimento

### DePanEstimate

Esta função usa o método troca fase (pelo rápido transformador Fourier) para estimação de movimento global. Usa uma região central de cada quadro (ou campo) como janela FFT para achar a correlação entre quadros e calcular os valores mais apropriados de trocas verticais e horizontais que ajustem o quadro atual ao prévio. Alguns parâmetros de correlação relativos são usados como medida de confiança e para detecção de mudança de cena. Em modo zoom, o plugin usa as sub-janelas esquerda e direita para calcular os deslocamentos e o zoom. A função usa o código livre FFT2D por Takuya Ooura. A produção é o clipe de serviço especial com dados de movimento codificados em quadros e arquivo log opcional.

Parâmetros do DePanEstimate:
clip - clipe de entrada
range - número do prévio (e também dos próximos) quadros (campos) próximos dos quadros pedidos para calcular movimento (valor inteiro >=0, padrão=1)
trust - limite de diferença de correlação máxima relativa do valor médio de mudança de cena (0.0 a 100.0, padrão=4.0)
winx - número de colunas (largura) da janela fft (deve ser potência de 2, padrão = máximo na largura do quadro).
winy - número de linhas (altura) da janela fft (deve ser potência de 2, padrão = máximo na altura do quadro).
dxmax - limite de x shift (padrão = winx/4)
dymax - limite de y shift (padrão = winy/4)
zoommax - máximo fator zoom (if = 1 (padrão), zoom não estimado)
improve - Melhora a estimação de zoom por repetição (padrão = false)
stab - diminuição da confiança calculada para grandes trocas (fator dxmax/(dxmax + stab*abs(dx)) ):
= 0.0 (padrão)- sem diminuição,
= 1.0 - metade em dxmax, dymax.
pixaspect - aspecto do píxel (padrão = 1.0)
info - mostra a informação do movimento no quadro (padrão = false)
log - produz arquivo de log com dados do movimento (no VirtualDub o formato plugin de Deshaker) (padrão none, não grava)
debug - produz dados para a utilidade debugview (padrão = false)
show - mostra a superfície de correlação (padrão = false)

### DePan

Gera o clipe com quadros de movimento compensado, usando dados de movimento calculados previamente por DePanEstimate.

Parâmetros do DePan:
clip - clipe de entrada (igual ao clipe de entrada para DePanEstimate)
data - clipe de serviço especial com dados de movimento codificados, produzido por DePanEstimate
offset - valor do balanço compensado para todas os quadros de entrada (campos, de -10.0 a 10.0, padrão = 0)
= 0 é transforme nulo.
= -1.0 é compensação total de movimento para trás do próximo quadro (campo) para o atual,
= 1.0 é compensação total de movimento à frente do quadro prévio (campo),
= -0.5 é meia compensação para trás do próximo quadro (campo),
= 0.5 é meia compensação à frente do quadro prévio (campo),
= 0.3333333 é uma compensação de um terço à frente do quadro prévio (campo),
= -1.5 é meia compensação para trás do próximo quadro (campo),
= 2.0 é compensação total de movimento à frente do quadro prévio (campo) e assim por diante.
subpixel - precisão de interpolação de píxel (padrão = 2)
0 - precisão de píxel (ao píxel mais próximo), nenhuma interpolação (rápido),
1 - precisão de subpíxel com interpolação bilinear,
2 - precisão de subpíxel com interpolação bicúbica (melhor).
pixaspect - aspecto do píxel (padrão = 1.0)
matchfields - compara a posição vertical dos campos entrelaçados para preservar a ordem dos campos, melhor denoising, etc., (padrão=true)
mirror - enche as bordas vazias com as refletidas dos píxeis das extremidades do quadro (em vez de preto):
0 - nenhum espelho (padrão);
1 - topo;
2 - fundo;
4 - esquerda;
8 - direita;
soma qualquer do acima - combinação (15 - tudo).
info - mostra info de movimento do quadro (padrão=false).
inputlog - nome do arquivo log de entrada no formato Deshaker (padrão - none, não lê)

Nota: O parâmetro offset de DePan é versão estendida do parâmetro delta de GenMotion.

### DePanInterleave

Gera longa série de clipes intercalados com grupos de quadros prévios de movimento compensado (em alguma gama), quadro original e quadros seguintes de movimento compensado (na gama) e os mesmos grupos para todos os quadros seguintes. Na realidade, combina a função DePan e Intercala a função (Avisynth interna) para fácil denoising temporal, com SelectEvery (prévia+próx+1, prévia) função para selecionar só quadros de fonte limpadas.

Parâmetros do DePanInterleave similares ao Depan:
clip - clipe de entrada (igual ao clipe de entrada para DePanEstimate)
data - clipe de serviço especial com dados de movimento codificados, produzido por DePanEstimate
prev - número de quadros prévios (campos) em grupo para compensar (inteiro>0, padrão=1)
next - número de próximos quadros (campos) em grupo para compensar (inteiro>0, padrão=1)
subpixel - precisão de interpolação de píxel (padrão= 2)
0 - precisão de píxel (ao píxel mais próximo), nenhuma interpolação (rápido),
1 - precisão de subpíxel com interpolação bilinear,
2 - precisão de subpíxel com interpolação bicúbica (melhor).
pixaspect - aspecto do píxel (padrão = 1.0)
matchfields - compara posição vertical de campos entrelaçados para melhor denoising, etc (padrão=true)
mirror - enche bordas vazias com píxeis de extremidade de quadro refletidos (em vez de preto):
0 - nenhum espelho (padrão);
1 - topo;
2 - fundo;
4 - esquerda;
8 - direita;
soma qualquer do acima - combinação (15 - tudo).
info - mostra info de movimento do quadro (padrão=false).
inputlog - nome do arquivo log de entrada no formato Deshaker (padrão - none, não lê)

### DePanStabilize

Esta função faz uma estabilização do movimento (deshake) suavizando o movimento global. O método de filtro inercial é usado (provavelmente parecido com Dugistudio plugin do VirtualDub).

Parâmetros do DePanStabilize:
clip - clipe de entrada (igual ao clipe de entrada para DePanEstimate)
data - clipe de serviço especial com dados de movimento codificados, produzido por DePanEstimate
cutoff - atalho de freqüência de vibração, Hertz (padrão = 1.0);
damping - relação de amortecer (padrão = 1.0);
addzoom - inclui zoom adaptável (padrão=false);
prev - atraso de algum quadro prévio para encher bordas vazias (em vez de preto):
0 - não enche (padrão),
1 - usa o quadro prévio mais próximo (n-1) para encher as extremidades do quadro atual (n),
2 - usa o quadro prévio (n-2) para encher (não todos na gama!) e assim por diante.
next - atraso de um próximo quadro para encher bordas vazias (em vez de preto):
0 - não enche (padrão ),
1 - usa o quadro prévio mais próximo (n+1) para encher as extremidades do quadro atual (n),
2 - usa o próximo quadro (n+2) para encher (não todos na gama!) e assim por diante.
mirror - enche bordas vazias com píxeis de extremidade de quadro refletidos (em vez de preto):
0 - nenhum espelho (padrão);
1 - topo;
2 - fundo;
4 - esquerda;
8 - direita;
soma qualquer do acima - combinação (15 - tudo).
dxmax - limite de correção horizontal, em píxeis (padrão = 60);
dymax - limite de correção vertical, em píxeis (padrão = 30);
zoommax - limite de correção de zoom (só zoom adaptável, padrão = 1.05);
rotmax - limite de correção de rotação, em graus (padrão = 1.0);
(se algum dos parâmetros máximo acima é positivo, então a correção será limitada a seu valor,
se negativo, a correção será nula e o quadro será fixado como quadro básico novo. Estes parâmetros também são usados como valores de escala para o filtro)
subpixel - precisão de interpolação do píxel (padrão = 2):
0 - precisão de píxel (ao píxel mais próximo), nenhuma interpolação (rápido);
1 - precisão de subpíxel com interpolação bilinear;
2 - precisão de subpíxel com interpolação bicúbica (melhor).
pixaspect - aspecto de píxel (padrão = 1.0);
info - mostra info do movimento em quadro (padrão=false).
inputlog - nome do arquivo log de entrada em formato Deshaker (nenhum padrão, não lê)

### Características e limitações da versão atual do plugin DePan

1. Trabalha só no formato de cor YV12.
2. Usa só zoom de panorama e movimento (sem rotação), mas dá avanço em velocidade e estabilidade.
Estimação em modo zoom não é muito precisa.
3. O clipe fonte deve ter o mesmo comprimento do clipe de dados de movimento.
4. T rabalha diretamente só com clipes progressivos.
Para fontes entrelaçadas, use a seguinte função SeparateFields do Avisynth e em seguida Weave (depois de compensação de movimento e denoising), com AssumeTTF e AssumeBFF (podem ser necessários ambos para campos compensados diferentes).
O plugin avalia e calcula o movimento de um campo (por vez) para o campo vizinho (do mesmo ou do quadro vizinho).
Para preservar a ordem dos campos (domínio) e melhor denoising, fixe o parâmetro MatchFields=true.
5. Modo Mirror (espelho) é único, mas ligeiramente diferente :-)
6. Não muito rápido, não otimizado por assembler.
7. Testado com Avisynth 2.5.3 e 2.55alpha.

### Usando DePan para preparo do clipe de movimento compensado intercalado com denoising após forte temporal

1. Carrega o clipe original (entrada), (I),
2. Faz o clipe (F) com compensação de movimento à frente total,
3. Faz o clipe (B) com compensação de movimento para trás total,
4. Faz um clipe intercalado, com quadros compensados antes de e depois de cada quadro original;
Nós teremos um clipe longo (com comprimento triplo), com cada 3 quadros sucessivos correspondidos ao mesmo tempo.
5. Aplique um filtro temporal que usa diferenças de píxel entre quadros prévios, atuais e próximos, (filtro de Fluxsmooth).
6. Selecione cada terceiro quadro (original não compensado, mas limpo) para produção.
O clipe limpo não terá muitos artefatos, produzidos por movimento global com denoising, que será mais forte na maioria das áreas (o panorama da câmera será compensado).

Notas: com DePanInterleave, organize 2,3,4 combinados para selecionar. Além disso, a gama pode ser maior que 1.

Amostra de escrito simples para clipe progressivo:

    AviSource("input.avi")
    LoadPlugin("depan.dll")
    LoadPlugin("fluxsmooth.dll")
    i = ConvertToYV12()
    mdata = DePanEstimate(i)
    DePanInterleave(i, data=mdata)

    FluxSmooth()

    SelectEvery(3, 1)
    ConvertToYUY2()

Para melhores resultados, você pode incluir temporariamente o parâmetro Info, para analisar a info e afinar alguns parâmetros (trust, dxmax etc.).

Amostra de escrito para clipe entrelaçado:

    AviSource("input.avi")
    LoadPlugin("depan.dll")
    LoadPlugin("fluxsmooth.dll")

    AssumeTFF()

    SeparateFields()
    i = ConvertToYV12()
    mdata = DePanEstimate(i, range=1, trust=5.5, log="depan.log")
    DePanInterleave(i,data=mdata, prev=1, next=1, matchfields=true)

    FluxSmooth()

    SelectEvery(3, 1)

    Weave()
    ConvertToYUY2()

Alguns filtros de denoising temporais satisfatórios:
CTMedian (Conditional Temporal Median) por Kevin Atkinson
e sua nova versão renomeada ao DeSpot (por Fizick) - para remoção de mancha
STMedianFilter por Tom Barry - trbarry@trbarry.com
FluxSmooth por Ross Thomas <ross@grinfinity.com>
RemoveDirt por Rainer Wittmann gorw@gmx.de
(o filtro Dust com LoadpluginEx provavelmente deve trabalhar também).

Por favor, faça uns testes para acrescentar filtros à lista! Para o método denoising proposto usando o DePan (previamente com GenMotion), tal filtro temporal tem que comparar o píxel com o prévio e os quadros seguintes e fazer uma suavização se a diferença entre o quadro prévio e o próximo é pequena. Estes filtros também podem fazer adicional compensação (pequena) de movimento interno local (como o filtro Dust que pode aumentar um pouco a velocidade devido à boa compensação de movimento global).

### Usando DePan para mudança de framerate

DePan pode ser usado como ferramenta de conversão e tarefas semelhantes para framerate.

Por exemplo, para mudar o framerate com factor=1.5, de 16.6 fps progressivo (filme velho de 8 mm) para 25 fps, use o escrito:

    AviSource("kino.avi")
    LoadPlugin("depan.dll")
    i = ConvertToYV12()

    data = DePanEstimate(i, range=1, trust=5)
    f1_3 = DePan(i, data, offset=1./3)
    b1_3 = DePan(i, data, offset=-1./3)
    Interleave(f1_3, i, b1_3)
    SelectEvery(6, 0, 1, 2)
    ConvertToYUY2()

### Usar o DePan para estabilização de movimento

DePan pode ser usado como uma ferramenta para suavizar o movimento global. O método de filtro inercial é usado na versão atual.

Amostra de escrito simples para clipe progressivo:

    AviSource("input.avi")
    LoadPlugin("depan.dll")
    LoadPlugin("fluxsmooth.dll")
    i = ConvertToYV12()
    mdata = DePanEstimate(i)
    DePanStabilize(i, data=mdata)

    ConvertToYUY2()

Nós podemos incluir e afinar os parâmetros, cutoff, dxmax, métodos de adição de extremidades etc, correspondentes ao seu clipe e você.

### Usando arquivos de log

A função DepanEstimate pode gravar arquivo log opcional com dados de movimento, em formato compatível Deshaker. Além disso, função Depan pode ler tais arquivos logs (neste modo trabalha como GenMotion, sem DepanEstimate, o clipe de dados é ignorado e o clipe fonte pode ser usado como dados falsos). O log Deshaker pode ser carregado em Depan e vice-versa. Depan também pode compensar zoom e rotação. Assim você pode carregar escritos AVS semelhantes no VirtualDub, e rodar segunda passagem do Deshaker para estabilização avançada de imagem (e codificação) do clipe filtrado. Claro que você tem que rodar o primeiro passe antes do DePanEstimate para fazer o arquivo Depan.log, que deve ser selecionado em Deshaker. Em vez disso, você pode incluir a função DePanStabilize(i,data) para escrito e rodar tudo em uma passagem!

### Formato do Arquivo Log Deshaker (após Gunnar Thalin)

Durante o Passo 1 o plugin Deshaker tenta achar o panorama, a rotação e o zoom que, quando aplicado à imagem atual, faz parecer com a imagem prévia (quase). Os valores em cada linha no arquivo são (da esquerda para a direita): número de quadro (ou campos), x - e y-panorama (em píxeis), rotação (em graus) e fator de zoom. Você pode editar o arquivo log manualmente (mas use formato de linha fixo). Você pode apagar linhas que estão completamente erradas (que você não as quer tentar melhorar). As aberturas nos números de quadros são tratadas como panorama zero, rotação zero e nenhuma escala. Se um quadro existir mais de uma vez no arquivo log, a última linha é usada.

Nota: Para fonte entrelaçada, info é para cada campo (A - primeiro, B - segundo pela vez)

### Formato framebuffer servidor-cliente DePan (geralmente para programadores)

Depan usa framebuffer do clipe especial para armazenar dados de movimento. Quando o cliente (Depan) pede os dados de movimento para o quadro n deste clipe, o servidor (DepanEstimate) cria o quadro e grava tais dados (do começo do framebuffer): um registro do cabeçalho e vários dados registros de movimento de quadro, da gama n para gama+n (nframes = 2*range+1 para quadros não de extremidades). A definição dos parâmetros de dados de movimento é a mesma do log Deshaker.

Em todas as versões de 0.6 uso estas estruturas:

    # definir DEPANSIGNATURE "depan06"

    typedef struct depanheaderstruct { // estrutura de cabeçalho depandata em framebuffer
    char signature[8]; // assinatura para checar
    int reserved; // para uso futuro
    int nframes; // número de registros com dados de movimento de quadros no framebuffer atual
    } depanheader;

    typedef struct depandatastruct { // estrutura de cada registro de dado de movimento de quadro em framebuffer
    int frame; // número do quadro
    float dx; // x troca (em píxeis) para este quadro
    float dy; // y troca (em píxeis, correspondido ao aspecto do píxel = 1)
    float zoom; // zoom
    float rot; // rotação (em graus), (agora =0 - nenhum dado de rotação calculado na versão atual)
    } depandata;

Nota 1. Depan usa dx=0.0 como marca de scenechange (mudança de cena).
Note 2. A produção DepanEstimate é aparada se não em modo show ou info.

### Mais info sobre Depan

Alguma discussão sobre GenMotion e plugins DePan pode ser achada no foro de AviSynth em: http://forum.doom9.org/forumdisplay.php?s=&forumid=33 in particular in thread http://forum.doom9.org/showthread.php?s=&threadid=66686

### Agradecimentos

Graças a Gunnar Thalin pela info detalhada sobre o formato do arquivo log Deshaker e discussões muito úteis. Graças a Takuya Ooura pelo código FFT2D livre e rápido.

### Mudanças das Versões:

- Version 0.1, April 25, 2004
  - first public (beta!).
- Version 0.2, April 27, 2004
  - fixed bug for non-integer Offset values.
- Version 0.3, May 15, 2004
  - fixed bug with DePanStabilize input parameters, set subpixel=2 as default
  - add zoom estimation and ZoomMax parameter, zoom and rotation compensation, log file input, MatchFields parameter.
- Version 0.4, May 16, 2004
  - fixed bug with MatchFields for big Offset
  - fixed bug with pixel position for nearest and bilinear interpolation
  - set default MatchFields=true, add pixel aspect, Russian doc.
- Version 0.5, May 22, 2004
  - fixed some bug with rotation in Depan
  - improved DepanStabilize: change stabilization method to inertial in wide range
  - added parameters freqmax, dxmax, dymax, zoommax, rotmax, inputlog.
- Version 0.6, May 28, 2004
  - minor changed and documented client-server format.
  - DepanEstimate: added stab parameter, scenechange at sharp trust changes, range may be 0, show correlation, crop output.
  - DepanStabilize: Freqmax is renamed to Cutoff, add adaptive zoom, Fill.
- Version 0.7, May 30, 2004
  - DepanEstimate: added improve zoom estimation.
- Version 0.8, June 06, 2004
  - DepanInterleave: replaced "Range" parameter to "Prev" and "Next".
- Version 0.9, June 13, 2004
  - all clients: added "Mirror" parameter to fill empty borders.

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