Merge pull request #28 from Datafalk/feat/doc

fix(doc): update documentation

docs/source/exploring_the_field/3d_products.rst

@@ -2,8 +2,8 @@
 ===========
 
 | CARS produces a geotiff file named ``dsm.tif`` that contains the Digital Surface Model in the required cartographic projection and the ground sampling distance defined by the user.
-| If the user provides an additional input image, an ortho-image ``color.tif`` is also produced. The latter is stackable to the DSM (See :ref:`getting_started`).
-| If the user saves points clouds as laz format (point_cloud_fusion, point_cloud_outliers_removing, point_cloud_rasterization), the points clouds are saved in laz compressed format with colors or graylevel image.
+| If the user provides an additional input image, an ortho-image ``clr.tif`` is also produced. The latter is stackable to the DSM (See :ref:`getting_started`).
+| If the user saves points clouds as `laz format <https://docs.fileformat.com/fr/gis/laz/>`_ (point_cloud_fusion, point_cloud_outliers_removing, point_cloud_rasterization), the points clouds are saved in laz compressed format with colors or graylevel image.
 
 These two products can be visualized with `QGIS <https://www.qgis.org/fr/site/>`_ for example.
 
@@ -19,5 +19,5 @@ These two products can be visualized with `QGIS <https://www.qgis.org/fr/site/>`
 +--------------+-------------+-------------+-------------------+
 |   dsm.tif    |   color.tif | `QGIS`_ Mix |    cloudcompare   |
 +--------------+-------------+-------------+-------------------+
-| |dsm|        |   |color|   |  |dsmclr|   |        |pc|       |
+| |dsm|        | |color|       |  |dsmclr|   |        |pc|       |
 +--------------+-------------+-------------+-------------------+

docs/source/exploring_the_field/from_satellite_images_to_dsm.rst

@@ -64,7 +64,8 @@ Generate a DSM step by step
 +--------------------------+---------------------------------------------+
 
 | For each point in one image, the software searches the corresponding point in the other image.
-| The color of the pixels (grayscale) in the image :ref:`below<matching>` corresponds to the shift value. Some pixels do not have a match (matching error due to moving objects, shadows etc.).
+| The color of the pixels (grayscale) in the image :ref:`below<matching>` corresponds to the shift value. Some pixels do not have a match, which are represented as transparent pixels in the image. These matching errors can occur due to various reasons such as moving objects, shadows, occlusions, or areas with insufficient texture.
+| The transparent pixels indicate areas where the matching algorithm couldn't find a reliable correspondence between the two images, highlighting regions of uncertainty in the matching process.
 
 
 .. _matching:
@@ -81,6 +82,7 @@ Generate a DSM step by step
 
 | The displacements obtained are transformed into positions in both images.
 | This allows to deduce lines of sight. The intersection of these lines gives a point in space: longitude, latitude, altitude (see :ref:`below<triangulation>`).
+| A line of sight is an imaginary straight line from the camera's perspective through a specific point in the image, extending into 3D space. It represents all possible 3D positions that could have produced that image point.
 
 .. _triangulation:
 

docs/source/exploring_the_field/masks_and_classifications_usage.rst

@@ -2,8 +2,9 @@ Mask and Classification Usage
 =============================
 
 | Photogrammetry is a technique that cannot reproduce altitude on water. This technique also has difficulties for moving elements or in shaded areas.
-| For this reason, it is possible to mask out areas or apply ad hoc processing to aid the matching stage.
+| For this reason, it is possible to mask out areas or apply ad hoc processing to aid the matching stage (see :ref:`mask_and_classification_usage`).
 
+.. _mask_and_classification_usage:
 Masks
 -----
 
@@ -22,4 +23,4 @@ Classification
 | Please, see the section :ref:`convert_image_to_binary_image` to make a multiband binary image with 1 bit per band.
 
 | All non-zeros values of the classification image will be considered as invalid data.
-| The classification can be used in each application by band name list selection parameter. See application ``classification`` parameter :ref:`configuration`..
+| The classification can be used in each application by band name list selection parameter. See application ``classification`` parameter :ref:`configuration`.

docs/source/getting_started.rst

@@ -14,6 +14,18 @@ Getting Started
 
     pip install cars
 
+* Alternatively, you can use the provided Dockerfile to build a Docker image for CARS:
+
+.. code-block:: console
+
+    # Clone the CARS repository
+    git clone https://github.com/CNES/cars.git
+    cd cars
+
+    # Build the Docker image
+    docker build -t cars:latest .
+
+
 * Get and extract data samples from CARS repository:
 
 .. code-block:: console
@@ -70,10 +82,10 @@ Open the ``dsm.tif`` DSM and ``color.tif`` color image in `QGIS`_ software.
 .. |dsmcolor| image:: images/dsm_clr.png
   :width: 100%
 
-+--------------+-----------------+---------------+
-|   dsm.tif    |   color.tif     | `QGIS`_ Mix   |
-+--------------+-----------------+---------------+
-| |dsm|        | |color|         |  |dsmcolor|   |
-+--------------+-----------------+---------------+
++--------------+-------------+-------------+
+|   dsm.tif    |   color.tif | `QGIS`_ Mix |
++--------------+-------------+-------------+
+| |dsm|        | |color|     |  |dsmcolor| |
++--------------+-------------+-------------+
 
 .. _`QGIS`: https://www.qgis.org/

docs/source/howto.rst

@@ -26,7 +26,7 @@ Example files are available here: https://intelligence.airbus.com/imagery/sample
 Maxar WorldView example files
 -----------------------------
 
-| Example files are available on AWS S3 through the SpaceNet challenge here: s3://spacenet-dataset/Hosted-Datasets/MVS_dataset/WV3/PAN/.
+| Example files are available on AWS S3 through the SpaceNet challenge here: `s3://spacenet-dataset/Hosted-Datasets/MVS_dataset/WV3/PAN/`
 | You need to install `aws-cli <https://github.com/aws/aws-cli>`_:
 
 .. code-block:: console
@@ -104,6 +104,7 @@ For example, if you want to monitor the computation of a CARS run:
 
 .. _make_a_simple_pan_sharpening:
 
+
 Make a simple pan sharpening
 ----------------------------
 
@@ -121,6 +122,24 @@ It can be recommended to apply a P+XS pansharpening with `OTB`_.
 
 .. _`OTB`: https://www.orfeo-toolbox.org/CookBook-8.0/C++/UserGuide.html#image-data-representation
 
+
+Convert RGB image to panchromatic image
+--------------------------------------
+
+CARS only uses panchromatic images for processing.
+
+If you have a multi-spectral image, you'll need to extract a single band to use, or convert it to a panchromatic image before using it with CARS.
+
+The line below use `"Grayscale Using Luminance" <https://en.wikipedia.org/wiki/Grayscale#Luma_coding_in_video_systems>`_ expression with `OTB BandMath <https://www.orfeo-toolbox.org/CookBook/Applications/app_BandMath.html>`_
+
+
+.. code-block:: console
+
+    otbcli_BandMath -il image.tif -out image_panchromatic.tif -exp "(0.2126 * im1b1 + 0.7152 * im1b2 + 0.0722 * im1b3)"
+
+
+
+
 .. _make_a_water_mask:
 
 Make a water mask
@@ -141,7 +160,7 @@ See next section to apply a gdal_translate to convert the mask with 1bit image s
 Convert image to binary image
 -----------------------------
 
-To translate single image or multiband image with several nbits per band to 1bit per band, it can be recommended to use gdal_translate as follows:
+To translate single image or multiband image with several nbits per band to 1bit per band, it can be recommended to use `gdal_translate <https://gdal.org/en/latest/programs/gdal_translate.html>`_ as follows:
 
 .. code-block:: console
 
@@ -171,7 +190,7 @@ Post process output
 Merge Laz files
 ---------------
 
-CARS generates several laz files corresponding to the tiles processed.
+CARS generates several `laz files <https://docs.fileformat.com/gis/laz/>`_ corresponding to the tiles processed.
 Merge can be done with `laszip`_. 
 
 To merge them:

docs/source/software_design/orchestrator.rst

@@ -7,7 +7,7 @@ Goals
 -----
 
 The *orchestrator* is the central element of CARS concepts.
-Its role is to ensure the communication between the computing technology,the *applications* and *CarsDatasets*.
+Its role is to ensure the communication between the *computing technology*, the *applications* and the *CarsDatasets*.
 
 Details
 -------
@@ -73,7 +73,7 @@ The cluster is the component which allows to realize the calculations.
 * `start_tasks` to compute each task that have been declared.
 * `future_iterator`: iterate over the `future` objects
 
-There are already 4 plugins, each one representing a mode:
+There are already 3 plugins, each one representing a mode:
 
 * *dask*
 

docs/source/software_design/plugin.rst

@@ -6,7 +6,7 @@ Plugin
 Geometry plugin
 ^^^^^^^^^^^^^^^^^
 
-Geometry plugins aim to enable the use of different geometry libraries, typically libGEO or Shareloc to perform CARS geometric operations which require the interpretation of the geometric models of the pairs to process.
+Geometry plugins aim to enable the use of different geometry libraries, typically `libGEO <https://github.com/OSGeo/libgeotiff>`_ or `Shareloc <https://github.com/CNES/shareloc>`_ to perform CARS geometric operations which require the interpretation of the geometric models of the pairs to process.
 Those operation are:
 
 * The epipolar grids computation
@@ -44,10 +44,10 @@ For example, if the AbstractGeometry object is defined in file `cars_geometry_pl
     )
 
 Mandatory methods
-
+++++++++++++++++++
 Currently, the `AbstractGeometry` class requires the implementation of the following mandatory methods and properties:
 
-* `conf_schema` which specify the user inputs json schema required by the geometric library
+* `conf_schema` which specify the user inputs json schema required by the geometric library.
 
 .. code-block:: python
 
@@ -104,7 +104,7 @@ Currently, the `AbstractGeometry` class requires the implementation of the follo
         :return: the long/lat/height numpy array in output of the triangulation
         """
 
-* `generate_epipolar_grids` which generates the left and right epipolar grids from the images of the pair and their geometrical models
+* `generate_epipolar_grids` which generates the left and right epipolar grids from the images of the pair and their geometrical models.
 
 .. code-block:: python
 
@@ -137,7 +137,7 @@ Currently, the `AbstractGeometry` class requires the implementation of the follo
             - the disparity to altitude ratio as a float
         """
 
-* `direct_loc` which performs direct localization operations
+* `direct_loc` which performs direct localization operations.
 
 .. code-block:: python
 
@@ -170,4 +170,4 @@ Available methods
 Some methods are available in the `AbstractGeometry` class that might be useful for any geometry plugin which would only perform the triangulation using sensor coordinates.
 CARS' API only provides as inputs of the geometry plugin triangulation method the epipolar coordinates for each image of the pair. Thus the `matches_to_sensor_coords` method enables any plugin to convert those coordinates into the corresponding sensor ones.
 
-`AbstractGeometry` implements the method `image_envelope`. It computes the ground footprint of an image in sensor geometry by projecting its four corners using the direct localization method. This method can be overloaded by any geometry plugin if necessary.
+`AbstractGeometry` implements the method `image_envelope`. It computes the ground footprint of an image in sensor geometry by projecting its four corners using the direct localization method. This method can be overloaded by any geometry plugin if necessary.

docs/source/troubleshooting_and_faqs.rst

@@ -64,7 +64,7 @@ Output data
 How to generate output files overview ?
 ---------------------------------------
 
-Considering bulky files, it can be recommended to generate an overview file with `GDAL`_ before opening it with QGIS:
+Considering bulky files, it can be recommended to generate an overview file with `GDAL`_ before opening it with `QGIS <https://www.qgis.org>`_:
 
 .. code-block:: console