Merge branch 'release' into 'master'

Release 0.3.0 See merge request 3d/PandoraBox/pandora2d!122
CNES · Jun 27, 2024 · f12ad29 · f12ad29
2 parents 99b62c0 + 5a1c7d6
commit f12ad29
Show file tree

Hide file tree

Showing 39 changed files with 438 additions and 57 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.3.0 (June 2024)
+
+### Added
+- Adding configuration file with dichotomy step. [#132]
+- Add warning documentation about stored disparity maps when step is different from 1. [#140]
+- Add warning documentation about pandora2d maturity. [#129]
+
+### Fixed
+- Fix estimation check_conf method. [#115]
+- Fix plot disparity maps with correct dataset on the notebook. [#139]
+- Fix update image path on README.md file. [#135]
+
+### Changed
+- Add ROI in test_dichotomy_execution. [#134]
+- Update version copyright. [#133]
+- Update README.md file. [#136]
+
 ## 0.3.0a1 (June 2024)
 
 ### Added

diff --git a/Makefile b/Makefile
@@ -60,7 +60,7 @@ install: venv ## install pandora2D (pip editable mode) without plugins
 
 .PHONY: install-plugin
 install-plugin: venv ## install pandora2D (pip editable mode) without plugins
-	@test -f ${PANDORA2D_VENV}/bin/pandora2d || ${PANDORA2D_VENV}/bin/pip install pandora-plugin-mccnn
+	@test -f ${PANDORA2D_VENV}/bin/pandora-plugin-mccnn || ${PANDORA2D_VENV}/bin/pip install pandora-plugin-mccnn
 	@test -f .git/hooks/pre-commit || echo echo "  Install pre-commit hook"
 	@test -f .git/hooks/pre-commit || ${PANDORA2D_VENV}/bin/pre-commit install
 	@echo "PANDORA2D installed in dev mode in virtualenv ${PANDORA2D_VENV}"
@@ -101,7 +101,7 @@ test-notebook: install ## run notebook tests only
 
 .PHONY: test-plugin
 test-plugin: install-plugin ## run plugins tests only
-	@${PANDORA2D_VENV}/bin/pytest -m "plugin_tests" --html=notebook-test-report.html
+	@${PANDORA2D_VENV}/bin/pytest -m "plugin_tests" --html=plugin-test-report.html
 
 ## Code quality, linting section
 

diff --git a/NOTICE b/NOTICE
@@ -1,4 +1,4 @@
-PANDORA2D Copyright (c) 2020 Centre National d'Etudes Spatiales (CNES).
+PANDORA2D Copyright (c) 2024 Centre National d'Etudes Spatiales (CNES).
 
 This software is distributed under the Apache Software License (ASL) v2.0, see
 LICENSE file or http://www.apache.org/licenses/LICENSE-2.0 for details.

diff --git a/README.md b/README.md
@@ -1,7 +1,5 @@
-# Pandora2D
-
 <h1 align="center">
-<a href="https://pandora2d.readthedocs.io/?badge=latest"><img src="https://raw.githubusercontent.com/CNES/Pandora2D/master/doc/sources/Images/logo/logo_pandora2d.png?inline=false" alt="Pandora2D coregistration Framework" width="432"></a>
+<a href="https://pandora2d.readthedocs.io/?badge=latest"><img src="https://raw.githubusercontent.com/CNES/Pandora2D/master/docs/source/Images/logo/logo_pandora2d.png?inline=false" alt="Pandora2D coregistration Framework" width="432"></a>
 </h1>
 
 <h4 align="center">Pandora2d  is a tool based on <a href="https://github.com/CNES/Pandora">Pandora<a/> to provide disparity maps
@@ -28,19 +26,21 @@ for images pairs with a combination of vertical and horizontal stereo.</h4>
 
 Before Pandora2D   |  After Pandora2D
 :-----------------:|:----------------:
-![](https://raw.githubusercontent.com/CNES/Pandora2D/master/doc/sources/Images/avant_recalage.gif?inline=false)  |  ![](https://raw.githubusercontent.com/CNES/Pandora2D/master/doc/sources/Images/apres_recalage.gif?inline=false)
+![](https://raw.githubusercontent.com/CNES/Pandora2D/master/docs/source/Images/avant_recalage.gif?inline=false)  |  ![](https://raw.githubusercontent.com/CNES/Pandora2D/master/docs/source/Images/apres_recalage.gif?inline=false)
 
 
 ## Install
 
 Pandora2D is available on Pypi and can be installed by:
 
 ```bash
-    #install pandora2d latest release
+    # Upgrade your pip by running:
+    pip install --upgrade pip
+    # Install pandora2d latest release
     pip install pandora2d
 ````
 
-## First step
+## Quick start
 
 Pandora2d requires a `config.json` to declare the pipeline and the pair of images to process.
 Download our data sample to start right away !
@@ -53,19 +53,19 @@ Download our data sample to start right away !
     wget https://raw.githubusercontent.com/CNES/Pandora2D/master/data_samples/images/maricopa.zip
     # Config file
     wget https://raw.githubusercontent.com/CNES/Pandora2D/master/data_samples/json_conf_files/a_basic_pipeline.json
-    #uncompress data
+    # Uncompress data
     unzip maricopa.zip
     # run Pandora2d
     pandora2d a_basic_pipeline.json output_dir
 
-    # The columns disparity map is saved in  "./res/columns_disparity.tif"
-    # The row disparity map is saved in  "./res/row_disparity.tif"
+    # The columns disparity map is saved in  "./output_dir/columns_disparity.tif"
+    # The row disparity map is saved in  "./output_dir/row_disparity.tif"
 ```
 
 ## To go further
 
 To create your own coregistration pipeline and choose among the variety of
-algorithms we provide, please consult [our online documentation](https://pandora2d.readthedocs.io/en/latest/).
+algorithms we provide, please consult [our online documentation](https://pandora2d.readthedocs.io).
 
 You will learn:
 
@@ -74,7 +74,7 @@ You will learn:
 
 ## Credits
 
-Our data test sample contains  modified  'Copernicus  Sentinel  data  [2021]'  for  Sentinel  data, provided by the Peps Sentinel2 website (CNES). 
+Our data test sample contains modified 'Copernicus Sentinel data [2021]', provided by the Peps Sentinel2 website (CNES).
 
 
 ## Related

diff --git a/data_samples/json_conf_files/a_dichotomy_pipeline.json b/data_samples/json_conf_files/a_dichotomy_pipeline.json
@@ -0,0 +1,30 @@
+{
+    "input": {
+      "left": {
+        "img": "./maricopa/left.tif",
+        "nodata": -9999
+      },
+      "right": {
+        "img": "./maricopa/right.tif",
+        "nodata": -9999
+      },
+      "col_disparity": [-2, 2],
+      "row_disparity": [-2, 2]
+    },
+    "pipeline": {
+      "matching_cost": {
+        "matching_cost_method": "zncc",
+        "window_size": 5,
+        "subpix": 2
+      },
+      "disparity": {
+        "disparity_method": "wta",
+        "invalid_disparity": "NaN"
+      },
+      "refinement": {
+        "refinement_method": "dichotomy",
+        "iterations": 2,
+        "filter": "bicubic"
+      }
+    }
+  }
diff --git a/docs/Makefile b/docs/Makefile
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2020 Centre National d'Etudes Spatiales (CNES).
+# Copyright (c) 2024 Centre National d'Etudes Spatiales (CNES).
 #
 # This file is part of PANDORA2D
 #

diff --git a/docs/make.bat b/docs/make.bat
@@ -1,5 +1,5 @@
 ::
-:: Copyright (c) 2020 Centre National d'Etudes Spatiales (CNES).
+:: Copyright (c) 2024 Centre National d'Etudes Spatiales (CNES).
 ::
 :: This file is part of PANDORA2D
 ::

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -1,7 +1,7 @@
 # pylint: skip-file
 #
 # coding: utf8
-# Copyright (c) 2020 Centre National d'Etudes Spatiales (CNES).
+# Copyright (c) 2024 Centre National d'Etudes Spatiales (CNES).
 #
 # This file is part of PANDORA2D
 #
@@ -39,9 +39,9 @@
 # -- Project information -----------------------------------------------------
 
 project = "Pandora2D"
-copyright = "2021, CNES"
+copyright = "2024, CNES"
 author = "CNES"
-version = "0.0.1"
+version = "0.3.0"
 # The full version, including alpha/beta/rc tags
 # not useful at the moment :  see  https://gitlab.cnes.fr/OutilsCommuns/CorrelateurChaine3D/pandora/issues/124
 # release = '0.2.0'

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,9 +6,17 @@
 Welcome to Pandora2D's documentation!
 =====================================
 
+**Pandora2D is an Image Registration framework. It computes 2D displacement maps from a pair of images taken over the same scene.** **It uses** `Pandora <https://github.com/cnes/pandora>`_.
 
-**Pandora2d  is a tool that provide disparity maps for images pairs with a combination in both direction.**
-**It uses** `Pandora <https://github.com/cnes/pandora>`_
+**The framework features a high level of modularity, allowing users to configure their own pipeline from a broad class of algorithms described in** :ref:`step_by_step` **chapter.**
+
+**Although Pandora2D was funded by CNES for Earth Observation applications, it is, in practice, agnostic to the type of sensor used for image acquisition.** 
+**Therefore, it can be used for any application derived from** `image registration <https://en.wikipedia.org/wiki/Image_registration>`_.
+
+.. warning::
+    The maturity of Pandora2D is tightly linked to the progress of the `Trishna mission <https://trishna.cnes.fr>`_.
+
+    As long as this mission is in the development phase, released versions of Pandora2d should be considered experimental. 
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/source/userguide/output.rst b/docs/source/userguide/output.rst
@@ -15,6 +15,12 @@ Saved images
         The output correlation_score map with optical flow refinement method contains the disparity
         step correlation score.
 
+.. warning::
+        If a step (in row or column) different from 1 is chosen at the :ref:`matching_cost` step, 
+        the disparity maps stored at the output of the pandora2D machine will be smaller than the image or ROI given by the user in the :ref:`inputs`. 
+
+        An issue has been opened on this subject, and the problem will be solved soon.  
+
 Saved configuration
 *******************
 

diff --git a/docs/source/userguide/step_by_step/estimation.rst b/docs/source/userguide/step_by_step/estimation.rst
@@ -49,20 +49,20 @@ Configuration and parameters
       - Exploration around the initial disparity for columns
       - int
       - 5
-      - >0, odd number
+      - >2, odd number
       - No
     * - *range_row*
       - Exploration around the initial disparity for rows
       - int
       - 5
-      - >0, odd number
+      - >2, odd number
       - No
     * - *sample_factor*
       - | Upsampling factor.
         | Images will be registered to within 1 / upsample_factor of a pixel
       - int
       - 1
-      - >= 1
+      - >= 1, multiple of 10
       - No
 
 

diff --git a/docs/source/userguide/step_by_step/matching_cost.rst b/docs/source/userguide/step_by_step/matching_cost.rst
@@ -5,7 +5,7 @@ Matching cost computation
 
 Theoretical basics
 ------------------
-The first step compute from the pair of images a cost volumes containing the similarity coefficients. The cost volumes is a 4D tensor with dims
+The first step computes from the pair of images a cost volumes containing the similarity coefficients. The cost volumes is a 4D tensor with dims
 [row, col, disp_col, disp_row].
 
 For each disparity in the input vertical disparity range (disp_min_row, disp_max_row),

diff --git a/docs/source/userguide/step_by_step/refinement.rst b/docs/source/userguide/step_by_step/refinement.rst
@@ -20,7 +20,7 @@ Optical_flow method
 -------------------
 .. warning::
     The optical flow method is still in an experimental phase.
-    The parameter window_size in the matching cost parameters require a value greater than 1 .
+    The parameter window_size in the matching cost parameters requires a value greater than 1 .
 
 Inspired by [Lucas & Kanade]_.'s algorithm
 

diff --git a/notebooks/introduction_and_basic_usage.ipynb b/notebooks/introduction_and_basic_usage.ipynb
@@ -596,6 +596,16 @@
     "pprint(pipeline_cfg)"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4c054794",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "image_datasets = create_datasets_from_inputs(input_config=checked_cfg[\"input\"])"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "finite-legislation",
@@ -695,8 +705,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plot_two_images(dataset[\"row_map\"].data,\n",
-    "                dataset[\"col_map\"].data,\n",
+    "plot_two_images(pandora2d_machine.dataset_disp_maps[\"row_map\"].data,\n",
+    "                pandora2d_machine.dataset_disp_maps[\"col_map\"].data,\n",
     "                \"Row disparity map\",\n",
     "                \"Columns disparity map\", \n",
     "                output_dir, \n",
@@ -746,8 +756,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plot_two_images(dataset[\"row_map\"].data,\n",
-    "                dataset[\"col_map\"].data,\n",
+    "plot_two_images(pandora2d_machine.dataset_disp_maps[\"row_map\"].data,\n",
+    "                pandora2d_machine.dataset_disp_maps[\"col_map\"].data,\n",
     "                \"Row refined disparity map\",\n",
     "                \"Columns refined disparity map\", \n",
     "                output_dir, \n",

diff --git a/pandora2d/Pandora2d.py b/pandora2d/Pandora2d.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # coding: utf8
 #
-# Copyright (c) 2021 Centre National d'Etudes Spatiales (CNES).
+# Copyright (c) 2024 Centre National d'Etudes Spatiales (CNES).
 #
 # This file is part of PANDORA2D
 #

diff --git a/pandora2d/__init__.py b/pandora2d/__init__.py
@@ -1,6 +1,3 @@
-#!/usr/bin/env python
-# coding: utf8
-#
 # Copyright (c) 2021 Centre National d'Etudes Spatiales (CNES).
 # Copyright (c) 2024 CS GROUP France
 #
@@ -24,16 +21,21 @@
 This module contains functions to run Pandora pipeline.
 """
 
+import json
+from pathlib import Path
 from typing import Dict
 
 import xarray as xr
+
 from pandora import read_config_file, setup_logging, import_plugin
 from pandora.common import save_config
 
 from pandora2d import common
 from pandora2d.check_configuration import check_conf, check_datasets
 from pandora2d.img_tools import create_datasets_from_inputs, get_roi_processing
 from pandora2d.state_machine import Pandora2DMachine
+from pandora2d import reporting
+from pandora2d.reporting import NumpyPrimitiveEncoder
 
 
 def run(
@@ -120,6 +122,9 @@ def main(cfg_path: str, path_output: str, verbose: bool) -> None:
     # save dataset if not empty
     if bool(dataset_disp_maps.data_vars):
         common.save_dataset(dataset_disp_maps, completed_cfg, path_output)
+        report = {"statistics": {"disparity": reporting.report_disparities(dataset_disp_maps)}}
+        with open(Path(path_output) / "report.json", "w", encoding="utf8") as fd:
+            json.dump(report, fd, indent=2, cls=NumpyPrimitiveEncoder)
     # Update output configuration with detailed margins
     completed_cfg["margins"] = pandora2d_machine.margins.to_dict()
     # save config

diff --git a/pandora2d/check_configuration.py b/pandora2d/check_configuration.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 #
-# Copyright (c) 2021 Centre National d'Etudes Spatiales (CNES).
+# Copyright (c) 2024 Centre National d'Etudes Spatiales (CNES).
 # Copyright (c) 2024 CS GROUP France
 #
 # This file is part of PANDORA2D

diff --git a/pandora2d/common.py b/pandora2d/common.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 #
-# Copyright (c) 2021 Centre National d'Etudes Spatiales (CNES).
+# Copyright (c) 2024 Centre National d'Etudes Spatiales (CNES).
 # Copyright (c) 2024 CS GROUP France
 #
 # This file is part of PANDORA2D

diff --git a/pandora2d/disparity/__init__.py b/pandora2d/disparity/__init__.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 # coding: utf8
 #
-# Copyright (c) 2021 Centre National d'Etudes Spatiales (CNES).
+# Copyright (c) 2024 Centre National d'Etudes Spatiales (CNES).
 #
 # This file is part of PANDORA2D
 #

diff --git a/pandora2d/disparity/disparity.py b/pandora2d/disparity/disparity.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 #
-# Copyright (c) 2021 Centre National d'Etudes Spatiales (CNES).
+# Copyright (c) 2024 Centre National d'Etudes Spatiales (CNES).
 # Copyright (c) 2024 CS GROUP France
 #
 # This file is part of PANDORA2D

diff --git a/pandora2d/estimation/phase_cross_correlation.py b/pandora2d/estimation/phase_cross_correlation.py
@@ -84,8 +84,8 @@ def check_conf(self, cfg: Dict) -> Dict:
         # Estimation schema config
         schema = {
             "estimation_method": And(str, lambda estimation_method: estimation_method in ["phase_cross_correlation"]),
-            "range_col": And(int, lambda range_col: range_col % 2 and range_col > 2),
-            "range_row": And(int, lambda range_row: range_row % 2 and range_row > 2),
+            "range_row": And(int, lambda range_row: range_row > 2, lambda range_row: range_row % 2 != 0),
+            "range_col": And(int, lambda range_col: range_col > 2, lambda range_col: range_col % 2 != 0),
             "sample_factor": And(int, lambda sf: sf % 10 == 0 or sf == 1, lambda sf: sf > 0),
         }
 

diff --git a/pandora2d/img_tools.py b/pandora2d/img_tools.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 #
-# Copyright (c) 2021 Centre National d'Etudes Spatiales (CNES).
+# Copyright (c) 2024 Centre National d'Etudes Spatiales (CNES).
 # Copyright (c) 2024 CS GROUP France
 #
 # This file is part of PANDORA2D