Merge branch 'release' into 'master'

Release 0.4.0 See merge request 3d/PandoraBox/pandora2d!156
CNES · Oct 1, 2024 · 0f6b45f · 0f6b45f
2 parents f12ad29 + d98c5b4
commit 0f6b45f
Show file tree

Hide file tree

Showing 144 changed files with 8,076 additions and 1,899 deletions.
diff --git a/.pylintrc b/.pylintrc
@@ -59,7 +59,8 @@ disable=raw-checker-failed,
         broad-except,
         unsubscriptable-object,
         unsupported-membership-test,
-        consider-using-f-string
+        consider-using-f-string,
+        unsupported-binary-operation
 
 
 # Enable the message, report, category or checker with the given id(s). You can

diff --git a/AUTHORS.md b/AUTHORS.md
@@ -22,6 +22,7 @@ This file keeps track of authors contributions.
 * Natalia Jimenez <[email protected]>
 * Quentin Fardet <[email protected]>
 * Jerome Lebreton <[email protected]>
+* Tommy Calendini <[email protected]>
 
 Update here with new contributors.
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.4.0 (October 2024)
+
+### Added
+- Add unit tests for optical flows. [#114]
+- Subpix taken into account in the dichotomy. [#148]
+- Adding requirement numbers to the test docstring. [#143]
+- Add requirement on html-report test. [#167]
+- Variable initial disparity added to the configuration file. [#76]
+- Adding cardinal sine module in interpolation filter. [#146]
+- Mask added to the configuration file. [#157]
+- Variable disparity taken into account in matching cost step. [#152]
+- Add constant.py and criteria.py files for masks. [#159]
+- Add right-disparity-outside criterion. [#162]
+- Variable disparity taken into account in dichotomy. [#154]
+- Add accuracy tests for dichotomy. [#126]
+- Variable disparity taken into account in optical flow. [#158]
+- Add first resource tests. [#174]
+- Setting up disparity grids at inputs. [#165]
+- Add left_nodata and right_nodata criteria. [#160]
+- Add left_invalid and right_invalid criteria. [#161]
+- Add criteria dataarray. [#163]
+- Add profiling. [#175]
+
+### Fixed
+- Fix the use of a step with the optical flow method in the refinement step. [#119]
+- Fix ROI coordinates when the first point is within the margin. [#142]
+- Fix sphinx errors. [#168]
+- Remove np.inf on cost volume. [#170]
+
+### Changed
+- State machine callback changed from after to before. [#144]
+- Update pylint version. [#153]
+- Documentation updated with new parameters for variable initial disparity. [#150]
+- Update numpy version. [#145]
+- Removal of disparity grids in the state machine. [#171]
+- Removal of the disparity condition with the interpolation step. [#169]
+- Update dichotomy documentation. [#166]
+- Pixel size output updated as a function of step size. [#164]
+
+
 ## 0.3.0 (June 2024)
 
 ### Added

diff --git a/data_samples/images/maricopa.zip b/data_samples/images/maricopa.zip
diff --git a/data_samples/json_conf_files/a_basic_pipeline.json b/data_samples/json_conf_files/a_basic_pipeline.json
@@ -8,8 +8,8 @@
       "img": "./maricopa/right.tif",
       "nodata": -9999
     },
-    "col_disparity": [-2, 2],
-    "row_disparity": [-2, 2]
+    "col_disparity": {"init": 0, "range": 2},
+    "row_disparity": {"init": 0, "range": 2}
   },
   "pipeline": {
     "matching_cost": {

diff --git a/data_samples/json_conf_files/a_dichotomy_pipeline.json b/data_samples/json_conf_files/a_dichotomy_pipeline.json
@@ -8,8 +8,8 @@
         "img": "./maricopa/right.tif",
         "nodata": -9999
       },
-      "col_disparity": [-2, 2],
-      "row_disparity": [-2, 2]
+      "col_disparity": {"init": 0, "range": 2},
+      "row_disparity": {"init": 0, "range": 2}
     },
     "pipeline": {
       "matching_cost": {
@@ -24,7 +24,7 @@
       "refinement": {
         "refinement_method": "dichotomy",
         "iterations": 2,
-        "filter": "bicubic"
+        "filter": { "method": "bicubic"}
       }
     }
-  }
+  }
diff --git a/data_samples/json_conf_files/a_variable_disparity_pipeline.json b/data_samples/json_conf_files/a_variable_disparity_pipeline.json
@@ -0,0 +1,30 @@
+{
+    "input": {
+      "left": {
+        "img": "./maricopa/left.tif",
+        "nodata": -9999
+      },
+      "right": {
+        "img": "./maricopa/right.tif",
+        "nodata": -9999
+      },
+      "col_disparity": {"init": "./maricopa/init_col_disparity_grid.tif", "range": 5},
+      "row_disparity": {"init": "./maricopa/init_row_disparity_grid.tif", "range": 5}
+    },
+    "pipeline": {
+      "matching_cost": {
+        "matching_cost_method": "zncc",
+        "window_size": 5
+      },
+      "disparity": {
+        "disparity_method": "wta",
+        "invalid_disparity": "NaN"
+      },
+      "refinement": {
+        "refinement_method": "dichotomy", 
+        "iterations": 2, 
+        "filter": {"method": "bicubic"}
+    }
+    }
+  }
+
diff --git a/docs/source/Images/estimation_schema.png b/docs/source/Images/estimation_schema.png
diff --git a/docs/source/Images/range_schema.png b/docs/source/Images/range_schema.png
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -59,6 +59,7 @@
     "sphinx_rtd_theme",
     "sphinx.ext.imgmath",
     "autoapi.extension",
+    "sphinx_tabs.tabs",
 ]
 
 autoapi_dirs = ["../../pandora2d"]

diff --git a/docs/source/exploring_the_field/initial_disparity.rst b/docs/source/exploring_the_field/initial_disparity.rst
@@ -9,21 +9,35 @@ There are two available methods to do this.
 Setting an interval
 -------------------
 
-In the configuration file, the user is required to enter disparity range, as a list with two elements each, indicating
-the minimum and maximum values for both row and columns disparity.
+In the configuration file, the user is required to enter disparity range for rows and columns, as a dictionary with 2 keys "init" and "range".
 
 .. code:: json
     :name: Setting disparity ranges example
 
     {
         "input":
             {
-                "col_disparity": [-2, 2],
-                "row_disparity": [-2, 2]
+                "col_disparity": {"init": 0, "range": 2},
+                "row_disparity": {"init": 0, "range": 2}
         }
     }
 
-
+.. note::
+    The "init" key can be either: 
+        - an integer if the initial disparity is common to every point in the image.
+        - a path to a disparity grid if each point has its own initial disparity value.
+
+    (see :ref:`inputs`)
+
+The min and max disparity would then be equal to (example for columns): 
+
+.. code:: python
+    :name: Calculating the min and the max of the disparity
+	
+    min_col_disparity = col_disparity["init"] - col_disparity["range"]
+    max_col_disparity = col_disparity["init"] + col_disparity["range"]
+    
+    
 .. figure:: ../Images/range_schema.png
 
 

diff --git a/docs/source/exploring_the_field/interpolation_filters.rst b/docs/source/exploring_the_field/interpolation_filters.rst
@@ -38,3 +38,20 @@ For both points to interpolate, the `fractional_shift` is `0.5`. Thus, the coeff
 :math:`x` values for which kernel is not null are available for :math:`a` ranging from :math:`-1` to :math:`2`.
 
 Thus, for an image in 2D, the filter is applied on an array of shape :math:`4 \times 4` where coefficients are applied on columns then lines.
+
+Sinc
+----
+
+This filter use a cardinal sine of the form:
+
+.. math::
+    \frac{\sin(x\ \pi)}{x\ \pi}
+
+Where :math:`x` is the fractional shift.
+
+Computed coefficients are windowed by a Gaussian of form:
+
+.. math::
+    \exp\left(\frac{-2\ \pi\ x^2}{\sigma^2}\right)
+
+Where :math:`\sigma` correspond to the size of the filter (half width of the window).
diff --git a/docs/source/userguide.rst b/docs/source/userguide.rst
@@ -14,6 +14,7 @@ Userguide
    userguide/output.rst
    userguide/as_an_api.rst
    userguide/faq.rst
+   userguide/expert_mode.rst
 
 
 
diff --git a/docs/source/userguide/as_an_api.rst b/docs/source/userguide/as_an_api.rst
@@ -34,8 +34,8 @@ Pandora2D provides a full python API which can be used to compute disparity maps
                 'img': img_right_path,
                 'nodata': np.nan,
             },
-            "col_disparity": [-2, 2],
-            "row_disparity": [-2, 2],
+            "col_disparity": {"init": 0, "range": 2},
+            "row_disparity": {"init": 0, "range": 2},
         },
         # define pipeline configuration
          'pipeline':{
@@ -200,4 +200,4 @@ In this case, matching cost cannot be computed for this pixel and the value will
 Then bit 1 will be set : *The point is invalid: the disparity interval to explore is
 absent in the right image* and the point disparity will be set to *invalid_disparity*.
 Moreover, everytime Pandora2D shifts the right image it introduces a new line set at *nodata_right* value. The matching
-cost cannot be computed for this line to.
+cost cannot be computed for this line to.
diff --git a/docs/source/userguide/expert_mode.rst b/docs/source/userguide/expert_mode.rst
@@ -0,0 +1,75 @@
+.. _Expert_mode:
+
+Expert mode
+===========
+
+Resume
+******
+
+The profiling expert mode is intended for users who want to measure the performance of Pandora2D on their personal computer.
+In the output folder, they can obtain a number of charts that calculate averages and other metrics for each step throughout the executions.
+
+How to profile more functions ?
+*******************************
+
+
+This option requires the user to be familiar with the pandora2d code.
+
+First, when they activate the `expert_mode` key in the configuration, they have access by default to performance
+information related to each stage of the state machine.
+All data is stored in the code in a `pandas.DataFrame` and locally in a CSV file, then presented as a graph in a PDF file.
+
+If the user wants to analyze the performance of another function, they can add the decorator
+`@mem_time_profile_profile(name="Function name")` above that function.
+If they want to obtain more metrics, they need to add them to the "metrics_list" in the `profiling.py` file.
+
+The graphs are handled by the `generate_figure` function.
+
+.. note::
+    Profiling certain functions can significantly increase execution times.
+
+
+
+Parameters and configuration :
+##############################
+
+Expert mode profiling section is composed of the following keys:
+
+    OptionalKey("folder_name"): str
+
+.. list-table:: Expert mode section
+    :header-rows: 1
+
+    * - Name
+      - Description
+      - Type
+      - Default value
+      - Required
+    * - *folder_name*
+      -
+      - str
+      -
+      - Yes
+
+**Example**
+
+.. code:: json
+    :name: Input example
+
+    {
+        "input":
+        {
+            // inputs content
+        }
+        ,
+        "pipeline" :
+        {
+            // pipeline content
+        },
+        "expert_mode":
+        {
+            "profiling":
+            {
+                "folder_name": "expert_mode_outputs"
+        }
+    }
diff --git a/docs/source/userguide/faq.rst b/docs/source/userguide/faq.rst
@@ -22,8 +22,8 @@ It is possible to add a step parameter in the configuration file. This parameter
                 "img": img_right_path,
                 "nodata": "NaN",
             },
-            "col_disparity": [-3, 3],
-            "row_disparity": [-3, 3],
+            "col_disparity": {"init": 0, "range": 3},
+            "row_disparity": {"init": 0, "range": 3},
         },
         "pipeline": {
             "matching_cost": {
@@ -60,8 +60,8 @@ It is possible to work on only one section of the image with an ROI. For this, t
                 "img": img_right_path,
                 "nodata": "NaN",
             },
-            "col_disparity": [-3, 3],
-            "row_disparity": [-3, 3],
+            "col_disparity": {"init": 0, "range": 3},
+            "row_disparity": {"init": 0, "range": 3},
         },
         "ROI": {
             "col": {"first": 10, "last": 100},