Merge branch 'release_branch_1_6_0' into 'master'

Release branch 1 6 0

See merge request 3d/PandoraBox/pandora!285

CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## Unreleased
 
+## 1.6.0a1 (Novembre 2023)
+
+### Added
+- Addition of a step for matching_cost (only usable with Pandora2d). [#337]
+- Adding roi in create_dataset_from_inputs. [#346]
+- Adding disparity in dataset image. [#331]
+- Check inter dataset. [#334]
+- Adding check_datasets function. [#335]
+
+
+### Fixed
+- Rationalisation of the allocate_costvolume function. [#320]
+- Remove right_disp_map. [#324]
+- Fix step use. [#353]
+- Fix disparities for Pandora2d. [#359]
+- Update get_metadata with classification and segmentation. [#361]
+- Update check_disparities. [#363]
+- Correction of notebooks. [#362]
+
+
+### Changed
+- Change dmin_dmax name function to get_min_max_from_grid. [#347]
+- New disparity storage in the dataset containing the disparity map. [#339]
+- Moving some "pipeline" checks to abstract classes. [#313]
+- New format for disparity in the user configuration file. [#330]
+- Change read_img function to create_dataset_from_inputs. [#345]
+- Move get_metadata function in img_tools file. [#328]
+- Update and move check_dataset function. [#333]
+
+
 ## 1.5.0 (April 2023)
 
 ### Added 

data_samples/json_conf_files/a_local_block_matching.json

@@ -2,13 +2,9 @@
   "input": {
     "img_left": "./left.png",
     "img_right": "./right.png",
-    "disp_min": -60,
-    "disp_max": 0
+    "disp_left": [-60, 0]
   },
   "pipeline": {
-    "right_disp_map": {
-      "method": "accurate"
-    },
     "matching_cost": {
       "matching_cost_method": "zncc",
       "window_size": 5,
@@ -20,6 +16,9 @@
     },
     "refinement": {
       "refinement_method": "quadratic"
+    },
+    "validation" : {
+      "validation_method": "cross_checking_accurate"
     }
   }
 }

data_samples/json_conf_files/a_local_block_matching_for_multiband_img.json

@@ -2,13 +2,9 @@
   "input": {
     "img_left": "./left_rgb.tif",
     "img_right": "./right_rgb.tif",
-    "disp_min": -60,
-    "disp_max": 0
+    "disp_left": [-60, 0]
   },
   "pipeline": {
-    "right_disp_map": {
-      "method": "accurate"
-    },
     "matching_cost": {
       "matching_cost_method": "zncc",
       "band": "r",
@@ -21,6 +17,9 @@
     },
     "refinement": {
       "refinement_method": "quadratic"
+    },
+    "validation" : {
+      "validation_method": "cross_checking_accurate"
     }
   }
 }

data_samples/json_conf_files/a_semi_global_matching.json

@@ -2,14 +2,10 @@
   "input": {
     "img_left": "./left.png",
     "img_right": "./right.png",
-    "disp_min": -60,
-    "disp_max": 0
+    "disp_left": [-60, 0]
   },
   "pipeline":
   {
-    "right_disp_map": {
-      "method": "accurate"
-    },
     "matching_cost" : {
       "matching_cost_method": "census",
       "window_size": 5,
@@ -37,7 +33,7 @@
       "filter_size": 3
     },
     "validation" : {
-      "validation_method": "cross_checking",
+      "validation_method": "cross_checking_accurate",
       "cross_checking_threshold": 1
     },
     "filter.this_time_after_validation" : {

data_samples/json_conf_files/a_semi_global_matching_with_mccnn_similarity_measure.json

@@ -2,14 +2,10 @@
   "input": {
     "img_left": "./left.png",
     "img_right": "./right.png",
-    "disp_min": -60,
-    "disp_max": 0
+    "disp_left": [-60, 0]
   },
   "pipeline":
   {
-    "right_disp_map": {
-      "method": "accurate"
-    },
     "matching_cost" : {
       "matching_cost_method": "mc_cnn",
       "window_size": 11,
@@ -32,7 +28,7 @@
       "filter_size": 3
     },
     "validation" : {
-      "validation_method": "cross_checking",
+      "validation_method": "cross_checking_accurate",
       "cross_checking_threshold": 1
     }
   }

docs/source/userguide/as_an_api.rst

@@ -12,7 +12,7 @@ Pandora provides a full python API which can be used to compute disparity maps a
 
     import pandora
     from pandora import common
-    from pandora.img_tools import read_img, read_disp
+    from pandora.img_tools import create_dataset_from_inputs, read_disp
     from pandora.check_configuration import check_conf, read_config_file
     from pandora.state_machine import PandoraMachine
 
@@ -44,17 +44,13 @@ Pandora provides a full python API which can be used to compute disparity maps a
         pandora.setup_logging(verbose)
 
         # Read images and masks
-        img_left = read_img(cfg['input']['img_left'], no_data=cfg['input']['nodata_left'],mask=cfg['input']['left_mask'],
-                            classif=cfg['input']['left_classif'], segm=cfg['input']['left_segm'])
-        img_right = read_img(cfg['input']['img_right'], no_data=cfg['input']['nodata_right'],
-                             mask=cfg['input']['right_mask'], classif=cfg['input']['right_classif'],
-                             segm=cfg['input']['right_segm'])
+        cfg_input = common.split_inputs(cfg['input'])
+        img_left = create_dataset_from_inputs(cfg_input['left'])
+        img_right = create_dataset_from_inputs(cfg_input['right'])
 
         # Read range of disparities
-        disp_min = read_disp(cfg['input']['disp_min'])
-        disp_max = read_disp(cfg['input']['disp_max'])
-        disp_min_right = read_disp(cfg['input']['disp_min_right'])
-        disp_max_right = read_disp(cfg['input']['disp_max_right'])
+        disp_min, disp_max = read_disp(cfg['input']['disp_left'])
+        disp_min_right, disp_max_right  = read_disp(cfg['input']['disp_right'])
 
         # Run the Pandora pipeline
         left, right = pandora.run(pandora_machine, img_left, img_right, disp_min, disp_max, cfg['pipeline'], disp_min_right,
@@ -89,24 +85,28 @@ Example of a monoband image dataset
 
 ::
 
-    Dimensions:  (col: 450, row: 375)
+    Dimensions:   (col: 450, row: 375)
     Coordinates:
-      * col      (col) int64 0 1 2 3 4 5 6 7 8 ... 442 443 444 445 446 447 448 449
-      * row      (row) int64 0 1 2 3 4 5 6 7 8 ... 367 368 369 370 371 372 373 374
+      * col       (col) int64 0 1 2 3 4 5 6 7 8 ... 442 443 444 445 446 447 448 449
+      * row       (row) int64 0 1 2 3 4 5 6 7 8 ... 367 368 369 370 371 372 373 374
+      * band_disp (band_disp) <U3 'min' 'max'
     Data variables:
-        im       (row, col) float32 88.0 85.0 84.0 83.0 ... 176.0 180.0 165.0 172.0
-        msk      (row, col) int16 0 0 0 0 0 0 0 0 0 0 0 0 ... 0 0 0 0 0 0 0 0 0 0 0
+        im        (row, col) float32 88.0 85.0 84.0 83.0 ... 176.0 180.0 165.0 172.0
+        msk       (row, col) int16 0 0 0 0 0 0 0 0 0 0 0 0 ... 0 0 0 0 0 0 0 0 0 0 0
+        disparity (band_disp, row, col) int16 -60.0 -60.0 -60.0 -60.0 -60.0 -60.0 ... -60.0 -60.0 -60.0 -60.0 -60.0
     Attributes:
         no_data_img:   0
         crs:           None
         transform:     | 1.00, 0.00, 0.00|\n| 0.00, 1.00, 0.00|\n| 0.00, 0.00, 1.00|
         valid_pixels:  0
         no_data_mask:  1
+        disparity_source <disparity in config file>
 
 Two data variables are created in this dataset:
 
  * *im*: contains input image data
  * *msk*: contains input mask data + no_data of input image
+ * *disparity*: contains input disparity data with two bands (min and max)
 
 Example of a multiband image dataset
 
@@ -117,13 +117,16 @@ Example of a multiband image dataset
       * band_im     (band_im) <U1 'r' 'g'
       * row      (row) int64 0 1 2 3 4
       * col      (col) int64 0 1 2 3 4 5
+      * band_disp (band_disp) <U3 'min' 'max'
     Data variables:
         im       (band_im, row, col) float64 1.0 1.0 1.0 1.0 1.0 ... 1.0 1.0 1.0 1.0
+        disparity (band_disp, row, col) int16 -60.0 -60.0 -60.0 -60.0 -60.0 -60.0 ... -60.0 -60.0 -60.0 -60.0 -60.0
     Attributes:
         valid_pixels:  0
         no_data_mask:  1
         crs:           None
         transform:     | 1.00, 0.00, 0.00|\n| 0.00, 1.00, 0.00|\n| 0.00, 0.00, 1.00|
+        disparity_source <disparity in config file>
 
 
 .. note::
@@ -200,13 +203,15 @@ This Dataset also has a :
 .. sourcecode:: text
 
     <xarray.Dataset>
-    Dimensions:             (col: 1000, indicator: 2, row: 1000)
+    Dimensions:             (row: 1000, col: 1000, disparity: 2, indicator: 2)
     Coordinates:
+      * disparity           (disparity) <U3 'min' 'max'
       * row                 (row) int64 0 1 2 3 4 5 6 ... 994 995 996 997 998 999
       * col                 (col) int64 0 1 2 3 4 5 6 ... 994 995 996 997 998 999
       * indicator           (indicator) object 'confidence_from_intensity_std' 'confidence_from_left_right_consistency'
     Data variables:
         disparity_map       (row, col) float32 0.0 0.0 0.0 0.0 ... 0.0 0.0 0.0 0.0
+        disparity_interval  (disparity) int64 -30 33
         validity_mask       (row, col) uint16 1 1 1 1 1 1 1 1 1 ... 1 1 1 1 1 1 1 1
         interpolated_coeff  (row, col) float64 nan nan nan nan ... nan nan nan nan
         confidence_measure  (row, col, indicator) float32 nan nan nan ... nan nan nan
@@ -218,11 +223,9 @@ This Dataset also has a :
         type_measure:           min
         cmax:                   24
         optimization:           sgm
-        disp_min:               -30
-        disp_max:               33
         refinement:             vfit
         filter:                 median
-        validation:             cross_checking
+        validation:             cross_checking_accurate
         interpolated_disparity: none
         crs:                    None
         transform:              | 1.00, 0.00, 0.00|\n| 0.00, 1.00, 0.00|\n| 0.00, 0.00, 1.00|
@@ -258,4 +261,4 @@ Right image
 Because of the disparity range choice, it is possible that there is no available point to scan on the right image.
 In this case, matching cost cannot be computed for this pixel and the value will be set to :math:`nan` .
 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*.
+absent in the right image* and the point disparity will be set to *invalid_disparity*.

docs/source/userguide/faq.rst

@@ -60,3 +60,62 @@ How do I add the band's names as metadata on a multiband image ?
       Description = g
     Band 3 Block=450x1 Type=Float32, ColorInterp=Blue
       Description = b
+
+
+How do I check my data without launching Pandora completely ?
+*************************************************************
+
+
+**Example using a python script and pandora library:**
+
+User configuration file, *pandora_conf.json*:
+
+.. code:: json
+    :name: user configuration example
+
+    {
+      "input": {
+        "img_left": "./left_rgb.tif",
+        "img_right": "./right_rgb.tif",
+        "disp_left": [-60, 0]
+      },
+      "pipeline": {
+        "matching_cost": {
+          "matching_cost_method": "zncc",
+          "band": "r",
+          "window_size": 5,
+          "subpix": 4
+        },
+        "disparity": {
+          "disparity_method": "wta",
+          "invalid_disparity": "NaN"
+        },
+        "refinement": {
+          "refinement_method": "quadratic"
+        },
+        "validation" : {
+          "validation_method": "cross_checking_accurate"
+        }
+      }
+    }
+
+
+And the python script.
+
+.. code-block:: bash
+
+    from pandora.img_tools import create_dataset_from_inputs
+    from pandora.check_configuration import check_dataset, read_config_file
+
+    # Read pandora_conf.json
+    user_cfg = read_config_file(cfg_path)
+
+    # Read images 
+    input_config = common.split_inputs(cfg["input"])
+    img_left = create_dataset_from_inputs(input_config=input_config["left"])
+    img_right = create_dataset_from_inputs(input_config=input_config["right"])
+
+    # Check dataset
+    check_dataset(img_left)
+    check_dataset(img_right)
+

docs/source/userguide/input.rst

@@ -16,12 +16,10 @@ Configuration and parameters
     *img_right*,Path to the right image,string,,Yes
     *nodata_left*,Nodata value for left image, int,-9999,No
     *nodata_right*,Nodata value for right image,int,-9999,No
-    *disp_min*,Minimal disparity,int or string,,Yes
-    *disp_max*,Maximal disparity,int or string,,Yes
+    *disp_left*,"Path to the disparity grid of the left image or [min, max] values","string or [int, int]",,Yes
     *left_mask*,Path to the left mask,string,"none",No
     *right_mask*,Path to the right mask,string,"none",No
-    *disp_min_right*,Path to the minimal disparity grid of the right image,string,"none",No
-    *disp_max_right*,Path to the maximal disparity grid of the right image,string,"none",No
+    *disp_right*,"Path to the disparity grid of the right image or [min, max] values","string or [int, int]","none",No
     *left_classif*,Path to the left classification map,string,"none",No
     *right_classif*,Path to the right classification map,string,"none",No
     *left_segm*,Path to the left segmentation map,string,"none",No
@@ -39,12 +37,14 @@ Images
 
 
 .. note::
-    - Parameters *disp_min* and *disp_max* can be the disparity range (type int) or the path to the grids
+    - Parameter *disp_left* can be the disparity range (type list[int, int]) or the path to the grids
       that contain the minimum and maximum disparity of a pixel (type string).
-    - If *disp_min* and *disp_max* are integers, then the range of disparities is fixed. The minimal and maximal
-      disparity of the right image are automatically calculated : *disp_min_right* = - *disp_max* and *disp_max_right* = - *disp_min*.
-    - If *disp_min* or *disp_max* are strings, that means they are paths to grids of disparities which have the same size as the input images.
-      Each pixel (x,y) of the grid corresponds to a local disparity (min for disp_min and max for disp_max) related to the same pixel (x, y) of the image.
+    - If *disp_left* is a tuple of integers, then the range of disparities is fixed. The minimal and maximal
+      disparity of the right image are automatically calculated :
+      *disp_right[0]* = - *disp_left[1]* and *disp_right[1]* = - *disp_left[0]*
+      where index `0` correspond to *min* and index `1` correspond to *max*.
+    - If *disp_left* is a string, that means it is the path to grids of disparities which have the same size as the input images.
+      Each pixel (x,y) of the grid corresponds to a local disparity (min for disp_left[0] and max for disp_left[1]) related to the same pixel (x, y) of the image.
     - Cross-checking step is not applicable if only left grids are provided (i.e the right one must be provided).
 
 .. note::

docs/source/userguide/output.rst

@@ -42,38 +42,9 @@ Saved images
     The confidence bands will be named: *confidence_from_ambiguity* and *confidence_from_intensity_std.after*.
 
 .. note::
-    Right products are only available if a *right_disp_map* parameter is activated and not equal to none.
-    Must be the first key of *pipeline*.
 
-+-----------------+---------------------------------------------+--------+---------------+--------------------------------+----------+
-| Name            | Description                                 | Type   | Default value | Available value                | Required |
-+=================+=============================================+========+===============+================================+==========+
-| *method*        | Method to compute the right disparity map   | string |   none        | "none", "accurate"             | Yes      |
-+-----------------+---------------------------------------------+--------+---------------+--------------------------------+----------+
+    Right products are only available if the *validation* step is present in the configuration file.
 
-Method value meaning:
-
-- *none*: the right disparity map is not calculated.
-- *accurate*: the right disparity map is calculated following the same pipeline as for the left disparity map, by inverting input images. The left one becomes the right one, the right one becomes the left one.
-
-Example
-*******
-
-.. sourcecode:: text
-
-    {
-      "input" : {
-            ...
-      },
-      "pipeline" :
-       {
-            "right_disp_map":
-            {
-                "method": "accurate",
-            }
-            ...
-        }
-    }
 
 .. _validity_mask: