|
|
|
# Table of Contents
|
|
|
|
|
|
|
|
[**7. Post-processing of Calculated Velocities**](#post-traitement-des-vitesses-calcul%C3%A9es)
|
|
|
|
|
|
|
|
- [Filtering Instantaneous Results](#wastebasket-filtrage-des-r%C3%A9sultats-instantan%C3%A9s)
|
|
|
|
- [1. Median Test](#1-test-m%C3%A9dian)
|
|
|
|
- [2. Velocity Threshold](#2-seuil-vitesse)
|
|
|
|
- [3. Correlation Threshold](#3-seuil-corr%C3%A9lation)
|
|
|
|
- [4. Correlation Peak](#4-pic-de-corr%C3%A9lation)
|
|
|
|
- [5. Velocity Distribution](#5-distribution-des-vitesses)
|
|
|
|
- [6. Perpendicular Velocity Dispersion to the Transect](#6-dispersion-des-vitesses-perpendiculaires-au-transect)
|
|
|
|
- [7. Angular Dispersion](#7-dispersion-angulaire)
|
|
|
|
- [Mean Results](#bar_chart-moyenne-des-r%C3%A9sultats)
|
|
|
|
- [Statistics of Velocity Results](#chart_with_upwards_trend-statistiques-des-r%C3%A9sultats-de-vitesse)
|
|
|
|
|
|
|
|
#
|
|
|
|
|
|
|
|
The post-processing step includes filtering and averaging the velocity results. It is also possible to display simple statistics on the velocity results.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# :wastebasket: Filtering Instantaneous Results
|
|
|
|
|
|
|
|
The **_Post-processing🡪 Filtering Instantaneous Results_** menu opens the filtering interface. Several filters are available:
|
|
|
|
1. Median Test: Filters based on the spatial consistency of velocities.
|
|
|
|
2. Velocity Threshold: Filters the components of velocity vectors.
|
|
|
|
3. Correlation Threshold: Filters based on the correlation level (tracer identification between images).
|
|
|
|
4. Correlation Peak: Filters based on the width of the correlation peak (tracer quality).
|
|
|
|
5. Velocity Distribution: Filters based on the temporal consistency of velocities.
|
|
|
|
6. Perpendicular Velocity Dispersion to the Transect: Filters checking the temporal consistency of velocities.
|
|
|
|
7. Angular Dispersion: Filters checking the temporal consistency of velocities.
|
|
|
|
|
|
|
|
These filters are applied sequentially, in the order presented above. This means that each filter processes the remaining velocities after the previous filters have been applied (so, only the median test directly processes all the calculated velocities). To use each filter, **activate the checkbox** and **enter the values**.
|
|
|
|
|
|
|
|
A brief overview is provided in this section. For more details, refer to the [detailed filter presentation](#présentation-détaillée-des-filtres).
|
|
|
|
|
|
|
|
## 1. Median Test 
|
|
|
|
|
|
|
|
| Parameter | Default Values | Description |
|
|
|
|
| --------- | -------------- | ----------- |
|
|
|
|
| **_epsilon_** | 0.1 pix | Normalization offset, accounts for local velocity fluctuations. |
|
|
|
|
| **_r0min_** | 2 pix | Tolerance threshold for deviation from the normalized median. |
|
|
|
|
| **_n_neighbor_** | 8 | Number of nearest neighbors considered. |
|
|
|
|
| **_dist_max_** | 10 m | Maximum distance to consider for neighbors. |
|
|
|
|
|
|
|
|
The median test is a **spatial consistency filter**: it rejects velocities that are inconsistent with their nearest neighbors (method proposed by [Westerweel & Scarano (2005)](https://link.springer.com/article/10.1007/s00348-005-0016-6)). The test is performed for each velocity component (Vx and Vy).
|
|
|
|
|
|
|
|
The steps of the median test are as follows:
|
|
|
|
- Detection of the **8 neighbors** at each point (parameter ***n_neighbor = 8*** and **_dist_max = 10 m_** by default).
|
|
|
|
- Calculation of the deviation from the median velocity of the neighbors. For better robustness, the deviation from the median is normalized by a **robust estimator of local velocity fluctuations** (parameter ***epsilon = 0.1 pix*** by default).
|
|
|
|
- Comparison of the calculated deviation to a **tolerance threshold** (parameter ***r0min = 2 pix*** by default).
|
|
|
|
- If the deviation **exceeds** the tolerance threshold, the velocity at the point is **rejected**.
|
|
|
|
|
|
|
|
> It is possible that the median test will reject many vectors in the case of a **complex velocity field with large spatial gradients**. In this case, the ***epsilon*** parameter can be adjusted (e.g., 0.2 or 0.3).
|
|
|
|
> - For complex velocity fields, it is recommended to use a dense grid to limit spatial gradients.
|
|
|
|
|
|
|
|
<details><summary><b> :mag_right: Deep Dive :tools: </b></summary>
|
|
|
|
<br>
|
|
|
|
|
|
|
|
The nearest neighbors are identified using a KD-Tree [(Bentley, 1975)](Manuel-utilisateur/Références-bibliographiques). The number of neighbors and the maximum distance to neighbors can be set as parameters.
|
|
|
|
|
|
|
|
> A large distance is set by default (10 m) so that only the neighbor count criterion constrains the detection. It would also be possible to set a large number of neighbors (50) and a reduced distance, for example, one meter, to include all neighbors within a one-meter radius around the point.
|
|
|
|
|
|
|
|
{width=140px}
|
|
|
|
|
|
|
|
Let \( u_0 \) be the velocity component at the point and \( u_i \) be the velocity component of a neighbor \( i \). In the case where 8 neighbors are considered, the median of the neighboring velocities \( u_{ref} \) is calculated as:
|
|
|
|
|
|
|
|
```math
|
|
|
|
u_{ref} = median(u_1, u_2, ..., u_8)
|
|
|
|
```
|
|
|
|
A robust estimator of local velocity fluctuations $K_v$ is calculated based on the deviations of the neighboring velocities from the median and a normalization offset $\epsilon$ entered by the user.
|
|
|
|
|
|
|
|
```math
|
|
|
|
r_i = u_i - u_{ref} \\
|
|
|
|
K_v = median(r_1, r_2, ..., r_8) + \epsilon
|
|
|
|
```
|
|
|
|
The deviation of the velocity at the point from the median velocity of the neighbors is normalized by the estimator of local velocity fluctuations $\K_v$
|
|
|
|
|
|
|
|
```math
|
|
|
|
r_0^* = \frac{|u_0 - u_{ref}|}{K_v} = \frac{|u_0 - u_{ref}|}{median(r_1, r_2, ..., r_8) + \epsilon}
|
|
|
|
```
|
|
|
|
|
|
|
|
The obtained deviation is finally compared to the tolerance threshold _**r0min**_
|
|
|
|
|
|
|
|
```math
|
|
|
|
if \quad r_0^* > r0_{min} \rightarrow reject
|
|
|
|
```
|
|
|
|
|
|
|
|
:clap: **End of in-depth explanations** :nerd_face:
|
|
|
|
|
|
|
|
#
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
## 2. Velocity Threshold 
|
|
|
|
|
|
|
|
| Parameter | Default Values | Description |
|
|
|
|
| --------- | -------------- | ----------- |
|
|
|
|
| **_Min Norm_** | 0 m/s | Lower limit of velocity norm |
|
|
|
|
| **_Max Norm_** | 1E30 m/s | Upper limit of velocity norm |
|
|
|
|
| **_Min Vx_** | -1E30 m/s | Lower limit of Vx component |
|
|
|
|
| **_Max Vx_** | 1E30 m/s | Upper limit of Vx component |
|
|
|
|
| **_Min Vy_** | -1E30 m/s | Lower limit of Vy component |
|
|
|
|
| **_Max Vy_** | 1E30 m/s | Upper limit of Vy component |
|
|
|
|
|
|
|
|
The velocity threshold filter allows you to keep only the velocities whose norm or Vx or Vy components fall within a defined range. ***Minimum and maximum values*** must be provided for each data (norm, Vx, Vy).
|
|
|
|
|
|
|
|
> Be cautious of the filter values for negative Vx/Vy velocities (min/max inversion)!
|
|
|
|
|
|
|
|
## 3. Correlation Threshold 
|
|
|
|
|
|
|
|
| Parameter | Default Values | Description |
|
|
|
|
| --------- | -------------- | ----------- |
|
|
|
|
| **_Min Correlation_** | 0.4 | Lower limit of measured correlation |
|
|
|
|
| **_Max Correlation_** | 0.98 | Upper limit of measured correlation |
|
|
|
|
|
|
|
|
The correlation threshold filter retains velocities only within a certain range of correlation values. See the page on [Principles of Tracer Movement Velocity Measurement](Manuel-utilisateur/Approfondissements#principes-de-la-mesure-de-la-vitesse-de-d%C3%A9placement-des-traceurs) for more details.
|
|
|
|
|
|
|
|
> The **minimum value** depends on the **quality of the tracers** and their **temporal consistency**.
|
|
|
|
> - For **non-deformable tracers** (hard objects, artificial tracers), **high correlations** (around 0.7) may be required.
|
|
|
|
> - For **deformable tracers** (turbulent patterns, foam), a **lower minimum threshold** (around 0.4) may be acceptable.
|
|
|
|
>
|
|
|
|
> Setting a maximum bound of 0.98 helps avoid artifacts if the calculation grid extends beyond the flow and encroaches on static areas (bank, image edge).
|
|
|
|
|
|
|
|
## 4. Correlation Peak 
|
|
|
|
|
|
|
|
| Parameter | Default Values | Description |
|
|
|
|
| --------- | -------------- | ----------- |
|
|
|
|
| **_rhomax_** | 0.5 | Tolerance threshold for the correlation peak width / displacement norm ratio |
|
|
|
|
|
|
|
|
The correlation peak width filter rejects points where the correlation peak is too wide compared to the calculated velocity.
|
|
|
|
|
|
|
|
> The width of the correlation peak indicates the **quality of tracer identification**.
|
|
|
|
>
|
|
|
|
> In the case of a **high-quality tracer** (easily identifiable), the **correlation peak is sharp and pronounced**. The peak width is therefore small compared to the measured displacement.
|
|
|
|
>
|
|
|
|
> In the case of a **low-quality tracer**, the **correlation peak is more spread out**. This indicates difficulty in precisely identifying the tracer’s position.
|
|
|
|
|
|
|
|
The ratio between the peak width and the velocity vector norm is calculated. The resulting ratio is compared to the **tolerance threshold of 0.5** (default parameter ***rhomax = 0.5***): if the ratio exceeds the threshold, the velocity at that point is rejected.
|
|
|
|
|
|
|
|
> A tolerance threshold of ***rhomax = 0.5*** means that the peak width should not exceed half (50%) of the calculated velocity norm.
|
|
|
|
|
|
|
|
<details><summary><b> :mag_right: Deep Dive :tools: </b></summary>
|
|
|
|
<br>
|
|
|
|
|
|
|
|
This filter analyzes the distribution of correlations around the peak.
|
|
|
|
|
|
|
|
{width="400px"}
|
|
|
|
|
|
|
|
Let $r_{max}$ be the value of the correlation peak. The peak width is measured at $0.8r_{max}$ (80% of the peak height).
|
|
|
|
The area $A_r$ (in pix²) around the peak where the correlation $r$ exceeds $0.8r_{max}$ is evaluated using a region-growing algorithm applied to the correlation field. The algorithm is initialized at the position of the correlation peak and runs with the condition $r \gt 0.8r_{max}$, considering a V4 neighborhood (4 cardinal neighbors).
|
|
|
|
|
|
|
|
> The region-growing algorithm helps identify a region that meets the defined condition around a starting pixel.
|
|
|
|
|
|
|
|
The equivalent radius $\rho$ of the area $A_r$ is calculated such that:
|
|
|
|
|
|
|
|
```math
|
|
|
|
\rho = \sqrt{\frac{A_r}{\pi}}
|
|
|
|
```
|
|
|
|
The radius $\rho$ is finally compared to the product of the displacement intensity $d$ and the tolerance threshold _**rhomax**_ :
|
|
|
|
|
|
|
|
```math
|
|
|
|
if \quad \rho > rho_{max}.d \rightarrow reject
|
|
|
|
```
|
|
|
|
|
|
|
|
:clap: **End of in-depth explanations** :nerd_face:
|
|
|
|
|
|
|
|
#
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
## 5. Velocity Distribution 
|
|
|
|
|
|
|
|
| Parameter | Default Values | Description |
|
|
|
|
| --------- | -------------- | ----------- |
|
|
|
|
| **_nstdvel_** | 3 | Stretch factor around the mean |
|
|
|
|
|
|
|
|
The velocity distribution filter ensures the temporal consistency of the results at a given point. The set of velocity norms at the point (after passing through the previous filters) are used to determine the mean norm at the point and its standard deviation.
|
|
|
|
|
|
|
|
For each time step, if the **norm deviates by more than 3 standard deviations from the mean norm**, the calculated velocity is rejected (default parameter ***n_std = 3***).
|
|
|
|
|
|
|
|
## 6. Dispersion of Perpendicular Velocities to the Transect 
|
|
|
|
|
|
|
|
| Parameter | Default Values | Description |
|
|
|
|
| --------- | -------------- | ----------- |
|
|
|
|
| **_CoVmax_** | 0.4 | Threshold for the coefficient of variation ($\frac{\sigma}{\mu}$) of the perpendicular velocity to the transect |
|
|
|
|
|
|
|
|
The filter for dispersion of perpendicular velocities to the transect rejects points with excessive velocity dispersion (perpendicular component to the transect). This filter is more drastic than the previous ones, **it directly rejects all velocities at the point**.
|
|
|
|
|
|
|
|
> :loudspeaker: _**Warning!**_
|
|
|
|
>
|
|
|
|
> This filter is dedicated to flow measurement applications. It **requires a bathymetric transect** to be provided.
|
|
|
|
|
|
|
|
The perpendicular component to the transect is determined for each velocity at the point (after passing through the previous filters). The **coefficient of variation** of this component is then calculated (the ratio of standard deviation to mean).
|
|
|
|
|
|
|
|
Points with a perpendicular velocity coefficient of variation greater than a **tolerance threshold of 0.4** are rejected (default parameter ***CoVmax = 0.4***).
|
|
|
|
|
|
|
|
## 7. Angular Dispersion 
|
|
|
|
|
|
|
|
| Parameter | Default Values | Description |
|
|
|
|
| --------- | -------------- | ----------- |
|
|
|
|
| **_circvarmax_** | 0.25 | Threshold for the circular variance |
|
|
|
|
|
|
|
|
The angular dispersion filter rejects points with excessive dispersion in the velocity orientations. This filter is more drastic than the previous ones, **it directly rejects all velocities at the point**.
|
|
|
|
|
|
|
|
All velocities at the point (after passing through the previous filters) are used to calculate the **circular variance**.
|
|
|
|
|
|
|
|
> The **circular variance** ranges from **0 (identical orientations)** to **1 (uniformly distributed orientations)**.
|
|
|
|
|
|
|
|
Points with a circular variance greater than a **tolerance threshold of 0.25** are rejected (default parameter ***circvarmax = 0.25***).
|
|
|
|
|
|
|
|
<details><summary><b> :mag_right: Deep Dive :tools: </b></summary>
|
|
|
|
<br>
|
|
|
|
|
|
|
|
The circular variance $circvar$ for a sample of $n$ observed angles $x_0, x_1,..., x_n$ is expressed as:
|
|
|
|
|
|
|
|
```math
|
|
|
|
circvar = 1 - \mid z \mid = 1 - \mid \frac{1}{n} \sum_{k=1}^{n}{e^{ix_k}} \mid
|
|
|
|
```
|
|
|
|
|
|
|
|
Where $|z|$ is the length of the complex number $z$ and $i$ is the imaginary unit.
|
|
|
|
|
|
|
|
The circular variance is then compared to the tolerance threshold _**circvarmax**_:
|
|
|
|
|
|
|
|
```math
|
|
|
|
si \quad circvar > circvar_{max} \rightarrow rejet
|
|
|
|
```
|
|
|
|
|
|
|
|
:clap: **End of in-depth explanations** :nerd_face:
|
|
|
|
|
|
|
|
#
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
#
|
|
|
|
|
|
|
|
The filtered instantaneous velocity fields are stored in the **_vel_filter_** folder. The layer group **_Filtered Results (F)_** is created.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
It allows visualizing the calculated velocities for image pairs in the form of a vector field (**_Velocities F_**), streamlines (**_Particles F._**, see how to calculate it here ([see how to calculate here](#\_Calcul_des_lignes)) or iso-contour plots (**_Isosurfaces F_**).
|
|
|
|
More details on [visualization and configuration of velocity layers here](#r%C3%A9f%C3%A9rences-bibliographiques). The graphical interface allows linking the visualization of images and calculated velocities with the button "Link/unlink images and velocities". .
|
|
|
|
|
|
|
|
# :bar_chart: Average of Results
|
|
|
|
|
|
|
|
The **_Post-processing🡪 Average of filtered instantaneous results_** menu opens the interface for calculating the average/median.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The **temporal median** of the results is proposed by default. It is possible to change to the **temporal average** of the results using the drop-down list.
|
|
|
|
|
|
|
|
The velocity fields to be aggregated are those selected in the list (by default, all filtered results are selected).
|
|
|
|
The **_Validate_** button initiates the calculation.
|
|
|
|
|
|
|
|
The averaged velocity field is stored in the file **_outputs.dir/average_vel.out_**. The layer group **_Average Results (M)_** (for averaged surface velocities) is created.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
It allows visualizing the averaged velocities calculated as a vector field (**_Velocities M._**), streamlines (**_Particles M_**, see how to calculate it here [see how to calculate here](#\_Calcul_des_lignes)) or iso-contour plots (**_Isosurfaces M_**). More details on [visualization and configuration of velocity layers here](Manuel-utilisateur/Affichage-des-résultats-de-vitesse). The graphical interface allows linking the visualization of images and calculated velocities with the button "Link/unlink images and velocities". 
|
|
|
|
|
|
|
|
# :chart_with_upwards_trend: Statistics of Velocity Results
|
|
|
|
|
|
|
|
The **_Post-processing🡪 Show result statistics..._** menu displays a summary (min, max, mean, median, standard deviation) of the raw and filtered velocity results: Vx and Vy components, correlation level (CORREL), norm (NORME), rotational (OMEGA, not yet implemented: displays value 4), divergence (DIVERG, not yet implemented: displays value 5). The statistics can be calculated for the results of all image pairs or for a specific image pair.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#
|
|
|
|
-> [**Next section: 8. Displaying velocity results**](Manuel-utilisateur/Affichage-des-résultats-de-vitesse) |
