filter field docs

e9d53685 · Olga Stamati · 13c8f74e · e9d53685 · e9d53685
Commit e9d53685 authored May 03, 2021 by Olga Stamati
--- a/docs/source/graphs/DIC.dot
+++ b/docs/source/graphs/DIC.dot
@@ -8,10 +8,10 @@ digraph G {
    DEF  [label="spam-deformImage",   color="#c46747", fillcolor="#FFEAE6", style="bold, filled", shape=ellipse, href="#pixel-search-script-spam-pixelsearch",  target="_top"];
    REG  [label="spam-reg",           color="#c46747", fillcolor="#FFEAE6", style="bold, filled", shape=ellipse, href="#registration-script-spam-reg", target="_top"];
    PS   [label="spam-pixelSearch",   color="#c46747", fillcolor="#FFEAE6", style="bold, filled", shape=ellipse, href="#pixel-search-script-spam-pixelsearch",  target="_top"];
-    LDIC [label="spam-ldic",          color="#c46747", fillcolor="#FFEAE6", style="bold, filled", shape=ellipse, href="#regular-grid-local-dic-script-spam-ldic", target="_top"];
+    FILT [label="spam-filterPhiField", color="#c46747", fillcolor="#FFEAE6", style="bold, filled", shape=ellipse, href="#filtering-script-spam-filterphifield", target="_top"];
+    LDIC [label="spam-ldic",  color="#c46747", fillcolor="#FFEAE6", style="bold, filled", shape=ellipse, href="#regular-grid-local-dic-script-spam-ldic", target="_top"];
    //PASS [label="spam-passPhiField", color="#c46747", fillcolor="#FFEAE6", style="bold, filled", shape=ellipse, href="#regular-grid-local-dic-script-spam-ldic", target="_top"];
-    FILT [label="spam-filterPhiField", color="#c46747", fillcolor="#FFEAE6", style="bold, filled", shape=ellipse, href="#filtering-script-spam-filterPhiField", target="_top"];
-    STR  [label="spam-regularStrain", color="#c46747", fillcolor="#FFEAE6", style="bold, filled", shape=ellipse, href="#regular-strain-script-spam-regularStrain", target="_top"];
+    STR  [label="spam-regularStrain", color="#c46747", fillcolor="#FFEAE6", style="bold, filled", shape=ellipse, href="#regular-strain-script-spam-regularstrain", target="_top"];

    // questions
    QEREG  [shape=box, label="misaligned images?"];
@@ -46,7 +46,7 @@ digraph G {
    REG -> REGR[label="Converged?"];
    //REGR -> RES;
    REGR -> DEF;
-    DEF -> RES;
+    //DEF -> RES;
    REGR -> PS[style=dashed, color="#c46747"];
    REGR -> LDIC[style=dashed, color="#c46747"];

@@ -55,16 +55,18 @@ digraph G {
    PS -> PSR[label="High CC?"];
    //PSR -> RES;
    PSR -> DEF//[constraint=false];
-    DEF -> RES;
+    //DEF -> RES;
+    PSR -> QFILT;
    PSR -> LDIC[style=dashed, color="#c46747"];
+    // filter ps

    // ldic
    LDICR [label="keep Φ field", shape=note, margin=0];
    LDIC -> LDICR;
    LDICR -> DEF//[constraint=false];
-    DEF   -> RES;
+    //DEF   -> RES;

-    // filter
+    // filter ldic
    LDICR -> QFILT;
    FILT -> STR;


--- a/docs/source/scripts.rst
+++ b/docs/source/scripts.rst
@@ -95,7 +95,7 @@ The result of this eye-alignment is a **single** Φ (linear and homogeneous defo


 ``Input:``
-.........
+.............

    **Required**

@@ -108,7 +108,7 @@ The result of this eye-alignment is a **single** Φ (linear and homogeneous defo
            .. HINT:: Make sure that the format of this file is compatible with a spam-style correlation file. (Run, for example, this script and check the result)

 ``Output:``
-.........
+.............

    - A *".tsv"* file containing:

@@ -194,7 +194,7 @@ It measures a **single** Φ (linear and homogeneous deformation function, see :r
 .. _here: https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/DIC.html#DIC.correlate.registerMultiscale

 ``Input:``
-.........
+.............

    **Required**

@@ -223,7 +223,7 @@ It measures a **single** Φ (linear and homogeneous deformation function, see :r
        - ``-def``: Ask to **save** the **deformed** im1 at the end of the iterative algorithm. This is the measured Φ applied to im1

 ``Output:``
-.........
+.............

    - A *".tsv"* file containing:

@@ -301,7 +301,7 @@ It measures a **displacement field** with a **1-pixel sensitivity** that maps im
            2. **Discrete** points. For example centres of mass of particles, if your objective is to perform particle tracking. See :ref:`labelToolkitTutorial` for more information. This mode is activated with ``-lab1`` input option

 ``Input:``
-.........
+.............

    **Required**

@@ -342,7 +342,7 @@ It measures a **displacement field** with a **1-pixel sensitivity** that maps im


 ``Output:``
-.........
+.............

    - A *".tsv"* file containing:

@@ -361,7 +361,7 @@ For the **structured grid** mode, the script can be run like this:
    $ source /path/to/spam/venv/bin/activate
    (spam) $ spam-pixelSearch \                                      # the script
                /path/to/my/data/im1.tif /path/to/my/data/im2.tif \  # the two 3D or 2D images (tiff files) to correlate
-                -mf1 /path/to/my/data/im1.tif -mc 0.5 \              # the mask of im1, and the coverage to skip the subvolumes
+                -mf1 /path/to/my/data/mask1.tif -mc 0.5 \            # the mask of im1 and the coverage to skip the subvolumes
                -pf /path/to/my/data/initialPhi.tsv -pfb 2 \         # initial guess, which was run in half-sized images
                -ns X -hws X \                                       # node spacing and half window size of the grid
                -sr -Z Z -Y Y -X X \                                 # search range
@@ -413,7 +413,7 @@ It measures a **displacement field** with a **1-pixel sensitivity** that maps im

                - There are **large** and **not homogeneous** deformations between the two configurations and 
                - The **texture** of the material is **weak**
-            Such a challeging case could look like this:
+            Such a challenging case could look like this:

        .. figure:: images/tutorial/scripts/psPropInput.png
                    :align: center
@@ -443,7 +443,7 @@ It measures a **displacement field** with a **1-pixel sensitivity** that maps im
        This means that this script can **not** run **in parallel**.

 ``Input:``
-.........
+.............

    **Required**

@@ -486,7 +486,7 @@ It measures a **displacement field** with a **1-pixel sensitivity** that maps im


 ``Output:``
-.........
+.............

    - A *".tsv"* file containing:

@@ -592,7 +592,7 @@ It measures a **field of deformation functions** that map each subvolume in im1
 .. _function: https://ttk.gricad-pages.univ-grenoble-alpes.fr/spam/DIC.html#DIC.correlate.register

 ``Input:``
-.........
+.............

    **Required**

@@ -624,7 +624,7 @@ It measures a **field of deformation functions** that map each subvolume in im1
        - ``-tif``: Ask for a tif **output** for **visualisation** of the displacement and the iterative algorithm information fields

 ``Output:``
-.........
+.............

    - A *".tsv"* file containing:

@@ -707,7 +707,7 @@ This script facilitates the manipulation of different Φ fields, applying a sing
        In both cases, you can choose which part of Φ (see :ref:`imageCorrelationTheory`) will be passed setting the input option ``-m``.

 ``Input:``
-.........
+.............

    **Required**

@@ -742,10 +742,11 @@ This script facilitates the manipulation of different Φ fields, applying a sing
        - ``-lab1`` The labelled image (see :ref:`labelToolkitTutorial`) from which the **output positions** are calculated (centres of mass of labels)

 ``Output:``
-.........
+.............
+
+    - A *".tsv"* file containing:

-    - A *".tsv"* file of the deformation field defined at the **new positions**:
-        - New points **position** (Z, Y, X), as defined by the input grid (``-ns``) or the labelled image (``-lab1``)
+        - New **positions** (Z, Y, X), as defined by the input grid (``-ns``) or the labelled image (``-lab1``)
        - The components of the applied or interpolated deformation function (*Fzz*, *Fzy*, *Fzx*, *Zdisp*, *etc*). Option ``-m`` defined which part of Φ was passed
        - For compatibility reasons, information related to the iterative algorithm in ``spam.DIC.register()`` (*iterations*, *error*, *deltaPhiNorm*, *returnStatus*). These are **totally irrelevant** to the result of this script

@@ -805,29 +806,36 @@ This script corrects/filters a deformation field.
            It is **recommended** to use this script **before** calculating **strains**.

 .. IMPORTANT::
-              This script **selects bad points** based on:
+              This script **selects bad points** based on a **threshold** on:
+
+                - 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   
+                - 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 *returnStatus* of the correlation algorithm, activated with
-                - the *local coherency value*, activated with

              This script **corrects bad points** based on:

-                - inverse distance weighting of closest (``-nr`` or ``-nn``) good neighbours, activated with
-                - gaussian distance weighting of closest (``-nr`` or ``-nn``) good neighbours, activated with
+                - inverse distance weighting of closest good neighbours, activated with
+                - gaussian distance weighting of closest good neighbours, activated with
                - local quadratic fit of closest good neighbours, activated with

+                Closest neighbours are selected based on distance ``-nr`` or number ``-nn``.
+
              This script **filters bad points** based on:

                - mean of closest neighbours
                - median filter

+              This script **ignores background points** based on a **threshold** on:
+                - the *return status*, activated with. The return status coefficient is the result of  
+

 ``Input:``
-.........
+.............

    **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` or :ref:`passPhi`

    **Optional**

@@ -841,10 +849,11 @@ This script corrects/filters a deformation field.


 ``Output:``
-.........
+.............

-    - A *".tsv"* file defined at the **same** points as the input field:
+    - A *".tsv"* file containing:

+        - 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**
        - Deformation functions of **points** defined as **bad** are **modified** based on the application asked
        - *returnStatus* of **points** defined as **bad** is **modified** (*returnsStatus* = 1)
@@ -892,7 +901,7 @@ This scripts calculates the strain field between im1 and im2, based on a displac
                For further details regarding the strain calculation in spam and the output of this script please see the detailed tutorial here :ref:`strainTutorial`.

 ``Input:``
-.........
+.............

    **Required**

@@ -909,7 +918,7 @@ This scripts calculates the strain field between im1 and im2, based on a displac
        - ``-tif``: Ask for a tif output for **visualisation** of the strain field

 ``Output:``
-.........
+.............

    - A *".tsv"* file containing: