OpenPIV

Visão Geral

OpenPIV (Open Particle Image Velocimetry) analisa o fluxo de fluidos a partir de pares de imagens PIV. Ele abrange pré-processamento, correlação cruzada, validação de vetores, substituição de valores atípicos, suavização e escalonamento para unidades físicas.

Tem como alvo openpiv 0.26.1. Verificações sintéticas foram executadas em Python 3.13, NumPy 2.5.3, SciPy 1.18.1, scikit-image 0.26.0 e Matplotlib 3.11.2. Rust não foi instalado; use backend="scipy" para o caminho testado. Veja evidências de revisão.

Quando Usar

Use esta habilidade ao trabalhar com pares de imagens PIV experimentais ou de visualização de fluxo: medindo campos de velocidade 2D, ajustando parâmetros da janela de interrogação, validando vetores ou derivando vorticidade, taxa de cisalhamento e estatísticas de turbulência. Para simular fluxo em vez de medi-lo, use uma habilidade de CFD em vez disso.

Início Rápido

Instale o OpenPIV:

uv pip install openpiv

# Pin it when the analysis needs to be reproducible -- this is the version every
# snippet below was checked against.
uv pip install "openpiv==0.26.1"

Execute a análise PIV em um par de imagens:

import numpy as np
from openpiv import tools, pyprocess, validation, filters, scaling

frame_a = tools.imread("image_a.bmp")
frame_b = tools.imread("image_b.bmp")

# Always returns (u, v, s2n); s2n is all NaN if sig2noise_method=None.
u, v, s2n = pyprocess.extended_search_area_piv(
    frame_a.astype(np.float32),
    frame_b.astype(np.float32),
    window_size=32,
    overlap=12,
    dt=0.02,
    search_area_size=38,
    correlation_method="linear",   # circular also supports extended search
    normalized_correlation=True,
    backend="scipy",
    sig2noise_method="peak2peak",
)

x, y = pyprocess.get_coordinates(
    image_size=frame_a.shape,
    search_area_size=38,
    overlap=12,
    center_on_field=False,         # matches sliding-window positions
)

# flags is a boolean array: True marks a spurious vector.
flags = validation.sig2noise_val(s2n, threshold=1.05) | ~np.isfinite(s2n)
flags |= ~np.isfinite(u) | ~np.isfinite(v)
u, v = filters.replace_outliers(u, v, flags, method="localmean", max_iter=3, kernel_size=2)

# Scale, then convert to right-handed image-boundary coordinates.
x, y, u, v = scaling.uniform(x, y, u, v, scaling_factor=96.52)
y, v = frame_a.shape[0] / 96.52 - y, -v

tools.save("vectors.txt", x, y, u, v, flags)

Ou use a CLI integrada, que também verifica as entradas e preserva máscaras e parâmetros de processamento:

python skills/openpiv/scripts/runner.py \
    --image frame_a.bmp --image frame_b.bmp --output_dir results --verbose

Conceitos Principais

Fundamentos do PIV

Particle Image Velocimetry é um método óptico para medir a velocidade do fluido rastreando partículas traçadoras iluminadas entre duas imagens.

Fluxo do processo:

1. Capture um par de imagens (frame_a, frame_b) separadas por um tempo conhecido dt.
2. Divida as imagens em janelas de interrogação.
3. Faça a correlação cruzada de janelas correspondentes para encontrar o deslocamento de pico.
4. Valide os vetores (sinal-ruído, alcance global, mediana local).
5. Substitua vetores espúrios por valores interpolados.
6. Escalone os deslocamentos de pixels para unidades físicas.

Parâmetros da Janela de Interrogação

window_size — janela de correlação em pixels (tipicamente 16–128). Janelas maiores fornecem melhor correlação, mas resolução espacial mais grosseira.

overlap — pixels compartilhados entre janelas adjacentes (tipicamente 50–75% de window_size). Maior sobreposição aumenta a densidade de vetores e o custo, mas vetores adjacentes se tornam correlacionados em vez de independentes.

search_area_size — a janela pesquisada no segundo quadro. Deve ser ≥ window_size; alguns pixels maiores acomodam deslocamentos maiores. Tanto "circular" quanto "linear" suportam pesquisa estendida. A CLI escolhe "linear" com preenchimento de zero e normalized_correlation=True para ela; isso não recupera deslocamento arbitrário nem elimina picos espúrios. O passo da grade é search_area_size - overlap, portanto, a sobreposição deve ser menor que a área de pesquisa.

Regras gerais: mantenha o maior deslocamento abaixo de cerca de um quarto de window_size e mire em 5–10 partículas por janela.

Razão Sinal-Ruído

s2n mede o quão distinto é o pico de correlação. sig2noise_method controla como ele é computado — "peak2mean" (o padrão da função) ou "peak2peak". Os dois estão em escalas diferentes, portanto, um limiar ajustado para um é sem sentido para o outro. Limiares típicos de peak2peak são 1.05–1.3.

…