Merge branch 'topic/default/doc' into 'branch/default'

Improve documentation

See merge request fluiddyn/fluidimage!125

Author: paugier

.hgignore

@@ -75,6 +75,7 @@ image_samples/*/*/params_*.xml
 image_samples/*/Images.bench
 image_samples/4th_PIV-Challenge_Case_E/E_Calibration_Images/Camera_0*/calib*.npz
 image_samples/Milestone/Images_many*
+image_samples/SurfTracking/Images.examples
 
 image_samples/Karman/Images.civ/*
 image_samples/*/Images.*_example*

doc/Makefile

@@ -164,4 +164,4 @@ open_html: html
 	firefox _build/html/index.html
 
 format:
-	mdformat *.md
+	mdformat *.md */*.md

doc/examples/bos_parallel.md

@@ -1,9 +1,8 @@
 # BOS computation
 
-This minimal example presents how to carry out a simple BOS
-computation.  See also the documentation of the class
-{class}`fluidimage.bos.Topology` and the work defined in
-the subpackage {mod}`fluidimage.works.piv`.
+This minimal example presents how to carry out a simple BOS computation. See also the
+documentation of the class {class}`fluidimage.bos.Topology` and the work defined in the
+subpackage {mod}`fluidimage.works.piv`.
 
 ```{literalinclude} bos_parallel.py
 ```

doc/examples/optflow_parallel.md

@@ -1,9 +1,9 @@
 # Optical flow computation in parallel with `TopologyOpticalFlow`
 
-This minimal example presents how to carry out a simple optical flow
-computation. See also the documentation of the class
-{class}`fluidimage.topologies.optical_flow.TopologyOpticalFlow` and the work
-defined in the subpackage {mod}`fluidimage.works.optical_flow`.
+This minimal example presents how to carry out a simple optical flow computation. See
+also the documentation of the class
+{class}`fluidimage.topologies.optical_flow.TopologyOpticalFlow` and the work defined in
+the subpackage {mod}`fluidimage.works.optical_flow`.
 
 ```{literalinclude} optflow_parallel.py
 ```

doc/examples/optflow_try_params.md

@@ -1,15 +1,14 @@
 # How to find good optical flow parameters?
 
-Asynchronous topologies are not very convenient to look for the best parameters
-for a computation. It is better to use the optical flow work directly as in
-this example:
+Asynchronous topologies are not very convenient to look for the best parameters for a
+computation. It is better to use the optical flow work directly as in this example:
 
 ```{literalinclude} optflow_try_params.py
 ```
 
 The parameters in `params.series` are used to define an object
-{class}`fluiddyn.util.serieofarrays.SeriesOfArrays`
-and to select one serie (which represents here a couple of images). It is also
-what is done internally in the topology. Have a look at
+{class}`fluiddyn.util.serieofarrays.SeriesOfArrays` and to select one serie (which
+represents here a couple of images). It is also what is done internally in the topology.
+Have a look at
 [our tutorial](https://fluiddyn.readthedocs.io/en/latest/tutorials/tuto_serieofarrays.html)
 to discover how to use this powerful tool!

doc/examples/piv_cluster.md

@@ -1,10 +1,10 @@
 # PIV computation on a cluster
 
-This minimal example presents how to carry out a simple PIV computation on a
-cluster. We need a script for the computation and a script to submit the job.
+This minimal example presents how to carry out a simple PIV computation on a cluster. We
+need a script for the computation and a script to submit the job.
 
-We call the script for the computation `piv_complete.py`. For idempotent job,
-it is important to set `params.saving.how = 'complete'`.
+We call the script for the computation `piv_complete.py`. For idempotent job, it is
+important to set `params.saving.how = 'complete'`.
 
 ```{literalinclude} piv_parallel_complete.py
 ```

doc/examples/piv_parallel.md

@@ -1,21 +1,19 @@
 # PIV computation in parallel with `TopologyPIV`
 
-This minimal example presents how to carry out a simple PIV computation.  See
-also the documentation of the class
-{class}`fluidimage.topologies.piv.TopologyPIV` and the work defined in the
-subpackage {mod}`fluidimage.works.piv`.
+This minimal example presents how to carry out a simple PIV computation. See also the
+documentation of the class {class}`fluidimage.topologies.piv.TopologyPIV` and the work
+defined in the subpackage {mod}`fluidimage.works.piv`.
 
 ```{literalinclude} piv_parallel.py
 ```
 
-We now show a similar example but with a simple preprocessing (using a function
-`im2im`):
+We now show a similar example but with a simple preprocessing (using a function `im2im`):
 
 ```{literalinclude} piv_parallel_im2im.py
 ```
 
-The file `my_example_im2im.py` should be importable (for example in the same
-directory than `piv_parallel_im2im.py`)
+The file `my_example_im2im.py` should be importable (for example in the same directory
+than `piv_parallel_im2im.py`)
 
 ```{literalinclude} my_example_im2im.py
 ```
@@ -25,8 +23,8 @@ Same thing but the preprocessing is done with a class `Im2Im`
 ```{literalinclude} piv_parallel_im2im_class.py
 ```
 
-The file `my_example_im2im_class.py` should be importable (for example in the
-same directory than `piv_parallel_im2im_class.py`)
+The file `my_example_im2im_class.py` should be importable (for example in the same
+directory than `piv_parallel_im2im_class.py`)
 
 ```{literalinclude} my_example_im2im_class.py
 ```

doc/examples/piv_try_params.md

@@ -1,17 +1,17 @@
 # How to find good PIV parameters?
 
 Fluidimage is designed to process several images in parallel with asynchronous
-"topologies". However, the asynchronous PIV topology is not very convenient to
-look for the best parameters for a PIV computation. It is better to use the PIV
-"work" directly as in these examples:
+"topologies". However, the asynchronous PIV topology is not very convenient to look for
+the best parameters for a PIV computation. It is better to use the PIV "work" directly as
+in these examples:
 
 ```{literalinclude} piv_try_params.py
 ```
 
 The parameters in `params.series` are used to define a
-{class}`fluiddyn.util.serieofarrays.SeriesOfArrays`
-and to select one serie (which represents here a couple of images). It is also
-what is done internally in the PIV topology. Have a look at
+{class}`fluiddyn.util.serieofarrays.SeriesOfArrays` and to select one serie (which
+represents here a couple of images). It is also what is done internally in the PIV
+topology. Have a look at
 [our tutorial](https://fluiddyn.readthedocs.io/en/latest/tutorials/tuto_serieofarrays.html)
 to discover how to use this powerful tool!
 

doc/examples/preproc.md

@@ -5,15 +5,15 @@ There are two main methods to preprocess images with Fluidimage:
 1. with user-defined preprocessing functions or classes, or
 2. with pre-defined preprocessing classes.
 
-For both methods, we use a `Work` class to try parameters and a `Topology`
-class to apply this work in parallel on a large serie of images.
-See the [](../overview_orga_package.md) for an explanation about this terminology.
+For both methods, we use a `Work` class to try parameters and a `Topology` class to apply
+this work in parallel on a large serie of images. See the [](../overview_orga_package.md)
+for an explanation about this terminology.
 
 ## 1. User-defined preprocessing
 
-Let's assume that you have a function or a class which gets an image as
-argument and returns a new image. If it is importable, you can use Fluidimage
-to first investigate which are the better parameters for your case:
+Let's assume that you have a function or a class which gets an image as argument and
+returns a new image. If it is importable, you can use Fluidimage to first investigate
+which are the better parameters for your case:
 
 ```{literalinclude} im2im_try_params.py
 ```
@@ -26,14 +26,13 @@ and then process a large serie of images in parallel with the class
 
 ## 2. Pre-defined preprocessing classes
 
-Fluidimage also provides pre-defined preprocessing classes to apply many
-standard preprocessing to images.
+Fluidimage also provides pre-defined preprocessing classes to apply many standard
+preprocessing to images.
 
 ### Preprocessing one serie
 
-To find the good parameter, you can use the class
-{class}`fluidimage.preproc.Work` (see also
-{mod}`fluidimage.preproc`).
+To find the good parameter, you can use the class {class}`fluidimage.preproc.Work` (see
+also {mod}`fluidimage.preproc`).
 
 ```{literalinclude} preproc_try_params.py
 ```

doc/examples/surface_tracking.py

@@ -1,23 +1,48 @@
+import skimage
+
 from fluidimage.topologies.surface_tracking import Topology
 
+
+def rescale_intensity(tuple_path_image):
+    """
+    Rescale image intensities, between the specified minima and maxima,
+    by using a multiplicative factor.
+
+    ----------
+    minima, maxima : float
+        Sets the range to which current intensities have to be rescaled.
+
+    """
+    path, img = tuple_path_image
+    # the processing can be adjusted depending on the value of the path.
+    print("process file:\n" + path)
+    minima = 0
+    maxima = 4095
+    out_range = (minima, maxima)
+    img_out = skimage.exposure.rescale_intensity(img, out_range=out_range)
+    return img_out
+
+
 params = Topology.create_default_params()
 
-params.film.fileName = "film.cine"
-params.film.path = "../../../surfacetracking/111713"
-params.film.path_ref = "../../../surfacetracking/reference_water"
+path_src = "../../image_samples/SurfTracking/Images"
+
+params.images.path = path_src
+params.images.path_ref = path_src
+params.images.str_subset = ":4:2"
+params.images.str_subset_ref = ":3"
+
+params.surface_tracking.xmin = 200
+params.surface_tracking.xmax = 250
+params.surface_tracking.correct_pos = True
+
+params.preproc.im2im = rescale_intensity
 
-# params.saving.how has to be equal to 'complete' for idempotent jobs
-# # (on clusters)
-params.saving.plot = False
-params.saving.how_many = 100
-params.saving.how = "complete"
-params.saving.postfix = "surface_tracking_example"
+params.saving.how = "recompute"
+# params.saving.path = str(self.path_out)
+params.saving.postfix = "examples"
 
 topology = Topology(params, logging_level="info")
 # topology.make_code_graphviz('topo.dot')
-seq = False
-topology.compute(sequential=seq)
 
-# not generating plots if seq mode is false
-if not seq:
-    params.saving.plot = False
+topology.compute(executor="exec_sequential")