Vous avez reçu un message "Your GitLab account has been locked ..." ? Pas d'inquiétude : lisez cet article https://docs.gricad-pages.univ-grenoble-alpes.fr/help/unlock/

Commit 5ccd943a authored by Olga Stamati's avatar Olga Stamati
Browse files

work on spam-filterPhiField docs

parent b3b325ce
Pipeline #66230 passed with stages
in 13 minutes and 49 seconds
This diff is collapsed.
This diff is collapsed.
...@@ -289,9 +289,10 @@ It measures a **displacement field** with a **1-pixel sensitivity** that maps im ...@@ -289,9 +289,10 @@ It measures a **displacement field** with a **1-pixel sensitivity** that maps im
.. tip:: When to use this script? .. tip:: When to use this script?
This step can be very useful when the deformation between the two configurations is **not homogeneous**, meaning that it can not be captured only by a single Φ (coming from :ref:`register` for example). This step can be very useful when the deformation between the two configurations is **not homogeneous**, meaning that it can **not** be captured only by a single Φ (coming from :ref:`register` for example).
Such a deformation could look like this: Such a deformation could look like this:
If you notice that there is also a **homogeneous** deformation (a rigid rotation for example), run :ref:`ereg`, or :ref:`register` and pass Φ as an initial guess to this script If you notice that there is also a **homogeneous** deformation (a rigid rotation for example), run :ref:`ereg`, or :ref:`register` and pass Φ as an initial guess to this script
.. IMPORTANT:: .. IMPORTANT::
...@@ -352,7 +353,7 @@ It measures a **displacement field** with a **1-pixel sensitivity** that maps im ...@@ -352,7 +353,7 @@ It measures a **displacement field** with a **1-pixel sensitivity** that maps im
- The return status of each subvolume (*returnStatus*). If it is -5 the subvolume has been skipped (due to ``-glt``, ``-ght`` or ``-mf1``) - The return status of each subvolume (*returnStatus*). If it is -5 the subvolume has been skipped (due to ``-glt``, ``-ght`` or ``-mf1``)
- For compatibility reasons, the F part of Φ is written as the identity matrix (see :ref:`imageCorrelationTheory` for explanation of the components of Φ). This is **totally irrelevant** to the result of this script - For compatibility reasons, the F part of Φ is written as the identity matrix (see :ref:`imageCorrelationTheory` for explanation of the components of Φ). This is **totally irrelevant** to the result of this script
- For compatibility reasons, information related to the iterative algorithm in ``spam.DIC.register()`` (*iterations*, *error*, *deltaPhiNorm*). These are **totally irrelevant** to the result of this script - For compatibility reasons, information related to the iterative algorithm in ``spam.DIC.register()`` (*iterations*, *error*, *deltaPhiNorm*). These are **totally irrelevant** to the result of this script
- If asked with *-tif* or *-vtk*: Files for the visualisation of the displacement and correlation coefficient fields - If asked with ``-tif`` or ``-vtk``: Files for the visualisation of the displacement and correlation coefficient fields
For the **structured grid** mode, the script can be run like this: For the **structured grid** mode, the script can be run like this:
...@@ -402,13 +403,15 @@ For the **discrete** mode, the script can be run like this: ...@@ -402,13 +403,15 @@ For the **discrete** mode, the script can be run like this:
Pixel search propagate script (spam-pixelSearchPropagate) Pixel search propagate script (spam-pixelSearchPropagate)
---------------------------------------------------------- ----------------------------------------------------------
This script performs a **sequential** point-by-point "pixel search" which computes a **cross-correlation** of a subvolume extracted in im1 based on a **gaussian weighted good neighbours guess** in a given search range in im2. This script performs a **sequential** point-by-point "pixel search" which computes a **cross-correlation** of a subvolume extracted in im1
based on a **gaussian weighted good neighbours guess** in a given search range in im2.
It is based on https://gricad-gitlab.univ-grenoble-alpes.fr/DVC/pt4d.
It measures a **displacement field** with a **1-pixel sensitivity** that maps im1 into im2. It measures a **displacement field** with a **1-pixel sensitivity** that maps im1 into im2.
.. tip:: When to use this script? .. tip:: When to use this script?
This can be seen as a *special* case of :ref:`pixelSearch`. This can be seen as a *special* case of :ref:`pixelSearch`.
It can be very useful when: It can be very useful when:
- There are **large** and **not homogeneous** deformations between the two configurations and - There are **large** and **not homogeneous** deformations between the two configurations and
...@@ -676,8 +679,8 @@ The script can be run like this: ...@@ -676,8 +679,8 @@ The script can be run like this:
| |
.. _passPhi: .. _passPhi:
Passing script (spam-passPhiField) Passing deformation script (spam-passPhiField)
------------------------------------- -------------------------------------------------
This script facilitates the manipulation of different Φ fields, applying a single deformation function to a series of points or passing a deformation field to a new basis. This script facilitates the manipulation of different Φ fields, applying a single deformation function to a series of points or passing a deformation field to a new basis.
...@@ -795,39 +798,59 @@ For **output** points defined in a **structured grid**, the script can be run li ...@@ -795,39 +798,59 @@ For **output** points defined in a **structured grid**, the script can be run li
Filtering script (spam-filterPhiField) Filtering script (spam-filterPhiField)
--------------------------------------------- ---------------------------------------------
This script corrects/filters a deformation field. This script **corrects** or **filters** a deformation **field**.
.. tip:: When to use this script? .. tip:: When to use this script?
When you are **generally satisfied** by your deformation field, but there are some **crazy points** that you would like to get rid of. - When you are **generally satisfied** with your deformation field, but there are some **crazy points** that you would like to get rid of.
Such a field could look like this: Such a field could look like this:
It is **recommended** to use this script **before** calculating **strains**. .. figure:: images/tutorial/scripts/filterInput.png
:align: center
.. IMPORTANT:: Displacement and return status fields coming from :ref:`ldic`
This script **selects bad points** based on a **threshold** on:
- It is **recommended** to use this script **before** calculating **strains**.
.. ATTENTION:: Only **one operation** is allowed at a time. This means that you can either ask for a **correction** **OR** a **filtering** of your input field.
You can for example:
1. run a first computation for correcting badly correlated points, check this result, and
2. if satisfied with the correction, give the resulted field as a new input to this script asking now for an overall filtering of the corrected field.
.. IMPORTANT::
- the **correlation coefficient**, activated with. A point's correlation coefficient is the result of :ref:`pixelSearch`, :ref:`pixelSearchPropagate`. Typically a coefficient **greater** than 0.9 is a good threshold If the **correction** of the field is asked, this script first selects bad points based on different metrics and then corrects them.
- the **return status**, activated with. A point's return status is the result of :ref:`ldic`, :ref:`ddic`. A return status of 2 means that the local algorithm has converged
- the **local coherency**, activated with. A point's local coherency is the average residual between the point's displacement and a second-order parabolic surface, fitted to the point's closest N neighbours and evaluated at the point's position. Typically, a point with a coherency value **smaller** than 0.1 is classified as coherent
The **selection** of bad points can be based on **one** of the following:
This script **corrects bad points** based on: - the **correlation coefficient**, activated with ``-scct``
A point's correlation coefficient is the result of :ref:`pixelSearch` or :ref:`pixelSearchPropagate`.
Typically a point with a coefficient **greater** than **0.99** is considered as **successfully** correlated
- inverse distance weighting of closest good neighbours, activated with - the **return status**, activated with ``-srs``
- gaussian distance weighting of closest good neighbours, activated with A point's return status is the result of :ref:`ldic` or :ref:`ddic`. A return status equals to **2** means that the local algorithm inside ``spam.DIC.register()`` has **converged**
- local quadratic fit of closest good neighbours, activated with
- the **local coherency**, activated with ``-slqc``
As per per Masullo and Theunissen 2016, a point's local coherency is the average residual between the point's displacement and a second-order parabolic surface,
fitted to the point's closest N neighbours and evaluated at the point's position.
Typically, a point with a coherency value **smaller** than **0.1** is classified as **coherent**.
The estimation of the local coherency is implemented in ``spam.DIC.estimateLocalQuadraticCoherency()`` and is based on https://gricad-gitlab.univ-grenoble-alpes.fr/DVC/pt4d.
The **correction** of bad points can be done with **one** of the following operations:
- inverse distance weighting of closest good neighbours, activated with ``-cint``
- gaussian distance weighting of closest good neighbours, activated with
- local quadratic fit of closest good neighbours, activated with ``-clqf``
Closest neighbours are selected based on distance ``-nr`` or number ``-nn``. Closest neighbours are selected based on distance ``-nr`` or number ``-nn``.
This script **filters bad points** based on: This script **filters** the input field based on:
- mean of closest neighbours - an overall median filter, activated with ``-fm`` with a given radius ``-fmr``
- median filter
This script **ignores background points** based on a **threshold** on: For both correction and filtering, this script by default **ignores background points** based their return status (*i.e, returnStatus=-5*). If you want to change this behaviour see ``-nomask`` input option.
- the *return status*, activated with. The return status coefficient is the result of
``Input:`` ``Input:``
...@@ -835,17 +858,28 @@ This script corrects/filters a deformation field. ...@@ -835,17 +858,28 @@ This script corrects/filters a deformation field.
**Required** **Required**
- ``-pf``: *".tsv"* file containing the deformation **field**. This file can come either from :ref:`pixelSearch`, :ref:`pixelSearchPropagate`, :ref:`ldic` or :ref:`passPhi` - ``-pf``: *".tsv"* file containing the deformation **field**. This file can come either from :ref:`pixelSearch`, :ref:`pixelSearchPropagate`, :ref:`ldic`, :ref:`passPhi` or :ref:`filterPhi`. If this file refers to downscaled images, use ``-pfb`` to set the correct binning ratio
**Optional** **Optional**
- ``-nr``: **Radius** (in pixels) inside which to extract **neighbours** - ``-np``: Number of **parallel processes** to use. If not passed, all the CPUs available in the system will be used
- ``-nn``: **Number** of **neighbours** to extract. Disactivates ``-nr`` - ``-nomask``: If activated, correlation points in **background** (*i.e,* with *returnStatus*=-5) will **not** be **ignored** from the correction/filtering operations. It is recommended **not** to activate this option
- ``-mask``: **Mask background** points. Points with *returnsStatus = -5* - ``-nr``: **Radius** (in pixels) inside which to extract **neighbours** for field interpolation. Disactivates ``-nn``
- ``-nn``: **Number** of **neighbours** to extract for field interpolation. Disactivates ``-nr``
- ``-srs``: Selects **bad** points based on their correlation **return status**. See ``-srst`` for setting the threshold. Disactivates ``-scc``, ``-slqc``, and ``-fm``
- ``-srst``: Return status **threshold below** which points are considered **bad**. Default behaviour selects points with RS<=1
- ``-scc``: Selects **bad** points based on their **correlation coefficient**. This is for fields coming from :ref:`pixelSearch`, :ref:`pixelSearchPropagate`. See ``-scct`` for setting the threshold. Disactivates ``-slqc``
- ``-scct``: Correlation coefficient **threshold below** which points are considered **bad**. Default behaviour selects points with CC<=0.99
- ``-slqc``: Selects **bad** points based on their local quadratic coherency value. Default behaviour selects points with coherency **bigger** or equal to 0.1. This threshold is **not** modifiable
- ``-cint``: **Corrects** selected **bad** points by an **interpolation** of the extracted neighbours' Φ with weights equal to the **inverse** of the **distance**. See ``-m`` to select the interpolated components
- ``-m``: Choose which **part of Φ** (see :ref:`imageCorrelationTheory`) will be corrected/filtered. If **"all"** all deformation components are considered (default behaviour). If **"rigid"** the rigid body motion is considered. If **"disp"** only displacements are considered
- ``-clqf``: **Corrects** selected **bad** points based on local **quadratic fit** of the extracted neighbours. The filt only applies to the **displacement** vector
- ``-fm``: Activates an overall **median filter** on the deformation field. ``-m`` can be set either as **"all"** or as **"disp"**. The filtering operation is allowed only if **none** of ``-scc``, ``-slqc`` or ``-slqc`` is passed
- ``-fmr``: Sets the radius (in pixels) of the median filter. Default behaviour is a radius of 1 pixel
- ``-od``: Defines the **output** directory - ``-od``: Defines the **output** directory
- ``-pre``: Defines the prefix for the **output** files - ``-pre``: Defines the prefix for the **output** files
- ``-vtk``: Ask for a vtk **output** for **visualisation** of the displacement field - ``-vtk``: Ask for a vtk **output** for **visualisation** of the displacement field
- ``-tif``: Ask for a tif output for **visualisation** of the displacement field - ``-tif``: Ask for a tif **output** for **visualisation** of the displacement field
``Output:`` ``Output:``
...@@ -854,31 +888,46 @@ This script corrects/filters a deformation field. ...@@ -854,31 +888,46 @@ This script corrects/filters a deformation field.
- A *".tsv"* file containing: - A *".tsv"* file containing:
- The points position (Z, Y, X) which are the **same** as the **input** field - The points position (Z, Y, X) which are the **same** as the **input** field
- Deformation functions and information related to the iterative algorithm status (*returnStatus*, *iterations*, *etc*) of **points** defined as **good** are **not modified** - The components of the points deformation functions (*Fzz*, *Fzy*, *Fzx*, *Zdisp*, *etc*). See :ref:`imageCorrelationTheory` for explanation of these components. Deformation components of **good** and **background** points are **not modified**
- Deformation functions of **points** defined as **bad** are **modified** based on the application asked - Information related to the iterative algorithm status (*returnStatus*, *iterations*, *etc*). Values of **good** and **background** points are **not modified**. *returnStatus* of corrected/filtered **bad** points is set equal to 1
- *returnStatus* of **points** defined as **bad** is **modified** (*returnsStatus* = 1)
- If asked with *-tif* or *-vtk*: Files containing the deformation components and the iterative algorithm's information as structured fields - If asked with *-tif* or *-vtk*: Files containing the corrected/filtered displacement fields
The script can be run like this: For a **correction** operation the script can be run like this:
.. code-block:: console .. code-block:: console
$ source path/to/spam/venv/bin/activate $ source path/to/spam/venv/bin/activate
(spam) $ spam-filterPhiField # the script (spam) $ spam-filterPhiField # the script
/path/to/my/data/PhiField.tsv\ # the file containing the correlation result -pf /path/to/my/data/PhiField.tsv\ # the file containing the deformation field
-mask \ # ignore background -srs -srst 1\ # select bad correlation points based on return status equal or less than 1
-tif -vtk # ask for TIFF file and VTK output of the strain field -nn 27\ # extract closest 27 good neighbours
-cint -m "disp"\ # correct displacements of bad points based on an inverse weighted distance interpolation of extracted good neighbours displacements
-tif -vtk # ask for TIFF file and VTK outputs
.. tip:: How to evaluate the result of this script?: The script can be run like this:
For a **filtering** operation the script can be run like this:
.. code-block:: console
- Compare the **residual fields**. Check the initial difference (im2.tif - im1.tif) and the new difference (im2.tif - im1Def.tif). Is the difference decreased? $ source path/to/spam/venv/bin/activate
(spam) $ spam-filterPhiField # the script
-pf /path/to/my/data/PhiField.tsv\ # the file containing the deformation field
-fm -fmr 2 -m "disp"\ # ask for a median filter of the input displacements with a radius of 2 px
-tif -vtk # ask for TIFF file and VTK outputs
.. tip:: The result of this script could look like this:
.. figure:: images/tutorial/scripts/filterOutput.png
:align: center
Are you satisfied with the measured displacement field? Are you satisfied with the corrected/filtered displacement field?
If yes, and you wish to run a last correlation step, **keep this Φ field** and move towards :ref:`ldic` or :ref:`ddic` - If no, retry by increasing ``-nr`` or ``-nn`` or ``-fmr``?
If yes, and you wish to proceed into measuring the **strains**, **keep this Φ field** and move towards :ref:`regularStrainScript` - If yes, and you wish to run a **last correlation** step, **keep this Φ field** and move towards :ref:`ldic`
- If yes, and you wish to proceed into measuring the **strains**, **keep this Φ field** and move towards :ref:`regularStrainScript`
| |
| |
| |
......
...@@ -2810,13 +2810,7 @@ def filterPhiField(parser): ...@@ -2810,13 +2810,7 @@ def filterPhiField(parser):
'--correct-by-local-quadratic-fit', '--correct-by-local-quadratic-fit',
action="store_true", action="store_true",
dest='CLQF', dest='CLQF',
help='Correct with a local interpolation with weights equal to the inverse of the distance?') help='Correct by a local quadratic fit? Only for displacements')
parser.add_argument('-lqcf',
'--local-quadratic-coherency-fit',
action="store_true",
dest='LQCF',
help='Correct bad points based on a fitting of the local quadratic coherency?')
#parser.add_argument('-dpt', #parser.add_argument('-dpt',
#'--delta-phi-norm-threshold', #'--delta-phi-norm-threshold',
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment