Skip to content

Commit

Permalink
Merge branch '935-corrections_docs' into 'master'
Browse files Browse the repository at this point in the history 
Correction de la documentation pour la release 0.10

Closes #931 and #935

See merge request 3d/cars-park/cars!775
  • Loading branch information
@dyoussef
dyoussef committed Dec 2, 2024
2 parents 9432097 + 6083741 commit ac423d6
Show file tree
Hide file tree
Showing 23 changed files with 1,953 additions and 1,875 deletions.
12 changes: 6 additions & 6 deletions .pre-commit-config.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,35 +3,35 @@ repos:
hooks:
- id: isort
name: isort
stages: [commit]
stages: [pre-commit]
language: system
entry: isort
types: [python]

- id: black
name: black
stages: [commit]
stages: [pre-commit]
language: system
entry: black
types: [python]

- id: flake8
name: flake8
stages: [commit]
stages: [pre-commit]
language: system
entry: flake8
types: [python]

- id: pylint
name: PyLint
stages: [commit]
stages: [pre-commit]
language: system
entry: pylint --rcfile=.pylintrc
files: \.py$

- id: sphinx-build
name: Build Sphinx Doc
stages: [push]
stages: [pre-push]
entry: make docs
language: system
files: ^(docs/.*|cars/.*)$
Expand All @@ -40,6 +40,6 @@ repos:
- id: jupyter-nb-clear-output
name: jupyter-nb-clear-output
files: \.ipynb$
stages: [commit]
stages: [pre-commit]
language: system
entry: jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace
35 changes: 13 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,30 +67,21 @@ docker run -w /data -v "$(pwd)"/data_gizeh:/data cnes/cars /data/configfile.json
with one configuration input file ("configfile.json") located in a "data" folder to be consistent with the previous command lines:
```
{
"inputs": {
"sensors" : {
"one": {
"image": "img1.tif",
"geomodel": "img1.geom"
},
"two": {
"image": "img2.tif",
"geomodel": "img2.geom"
},
"three": {
"image": "img3.tif",
"geomodel": "img3.geom"
}
"inputs": {
"sensors" : {
"one": {
"image": "img1.tif",
"geomodel": "img1.geom"
},
"pairing": [["one", "two"],["one", "three"]],
"initial_elevation": "srtm_dir/N29E031_KHEOPS.tif"
},
"output": {
"out_dir": "outresults"
"two": {
"image": "img2.tif",
"geomodel": "img2.geom"
}
}
},
"output": {
"directory": "outresults"
}
}
```
Expand Down
2 changes: 1 addition & 1 deletion docs/source/_static/css/my_custom.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,5 @@
}

.wy-nav-content {
max-width: 80% !important;
max-width: 100% !important;
}
2 changes: 1 addition & 1 deletion docs/source/exploring_the_field/3d_products.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

| 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 <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.
| If the user saves point clouds as `laz format <https://docs.fileformat.com/fr/gis/laz/>`_, the point 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.

Expand Down
119 changes: 39 additions & 80 deletions docs/source/exploring_the_field/from_satellite_images_to_dsm.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,23 +9,22 @@ Generate a DSM step by step
.. |resampling| image:: ../images/dense.resampling.drawio.png
:target: index.html#resampling

.. |resampling_circled| image:: ../images/dense.resampling.circled.drawio.png

.. |matching| image:: ../images/dense.matching.drawio.png
:target: index.html#matching

.. |matching_circled| image:: ../images/dense.matching.circled.drawio.png

.. |triangulation| image:: ../images/dense.triangulation.drawio.png
:target: index.html#triangulation

.. |triangulation_circled| image:: ../images/dense.triangulation.circled.drawio.png

.. |rasterization| image:: ../images/dense.rasterization.drawio.png
:target: index.html#rasterization

.. |matching_spa| image:: ../images/sparse.matching.drawio.png
:target: index.html#matching_sparse

.. |triangulation_spa| image:: ../images/sparse.triangulation.drawio.png
:target: index.html#triangulation_sparse

.. |rasterization_spa| image:: ../images/sparse.rasterization.drawio.png
:target: index.html#rasterization_sparse
.. |rasterization_circled| image:: ../images/dense.rasterization.circled.drawio.png

.. |resampling_image| image:: ../images/crop_image10.gif

Expand All @@ -48,24 +47,24 @@ Generate a DSM step by step

| Images are first resampled in epipolar geometry: by changing viewpoints, objects pixels move along a line.
| This enables a one-dimensional search (computer performance + error limitation).
| The pixels shifting along others directions doesn't taking account and it corresponds to fast moving objets (for instance like vehicle moving from bottom to top, see :ref:`below<resampling>`)
| The pixels shifting along other directions are not taken into account : it corresponds to fast moving objects like vehicles.

.. _resampling:

+--------------------------+---------------------------------------------+
| Pipeline | Resampling |
+--------------------------+---------------------------------------------+
| |images_models| |br| | |resampling_image| |
| |resampling| |br| | |
| |matching| |br| | |
| |triangulation| |br| | |
| |rasterization| |br| | |
+--------------------------+---------------------------------------------+
+---------------------------+---------------------------------------------+
| Pipeline | Resampling |
+---------------------------+---------------------------------------------+
| |images_models| |br| | |resampling_image| |
| |resampling_circled| |br| | |
| |matching| |br| | |
| |triangulation| |br| | |
| |rasterization| |br| | |
+---------------------------+---------------------------------------------+

| 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, 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.
| The color of the pixels (grayscale) in the image :ref:`below<matching>` corresponds to the shift value. Pixels with no match are displayed as transparent pixels in the image below.
| 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. These matching errors can occur due to various reasons such as moving objects, shadows, occlusions, or areas with insufficient texture.
.. _matching:

Expand All @@ -74,7 +73,7 @@ Generate a DSM step by step
+--------------------------+---------------------------------------------+
| |images_models| |br| | |matching_image| |
| |resampling| |br| | |
| |matching| |br| | |
| |matching_circled| |br| | |
| |triangulation| |br| | |
| |rasterization| |br| | |
+--------------------------+---------------------------------------------+
Expand All @@ -85,34 +84,34 @@ Generate a DSM step by step
.. _triangulation:

+--------------------------+---------------------------------------------+
| Pipeline | Triangulation |
+--------------------------+---------------------------------------------+
| |images_models| |br| | |triangulation_image| |
| |resampling| |br| | |
| |matching| |br| | |
| |triangulation| |br| | |
| |rasterization| |br| | |
+--------------------------+---------------------------------------------+
+------------------------------+---------------------------------------------+
| Pipeline | Triangulation |
+------------------------------+---------------------------------------------+
| |images_models| |br| | |triangulation_image| |
| |resampling| |br| | |
| |matching| |br| | |
| |triangulation_circled| |br| | |
| |rasterization| |br| | |
+------------------------------+---------------------------------------------+

To obtain a raster image, the final process projects each point into a 2D grid: altitudes and colors (see :ref:`below<rasterization>`).

.. _rasterization:

+--------------------------+---------------------------------------------+
| Pipeline | Rasterization |
+--------------------------+---------------------------------------------+
| |images_models| |br| | |rasterization_image| |
| |resampling| |br| | |
| |matching| |br| | |
| |triangulation| |br| | |
| |rasterization| |br| | |
+--------------------------+---------------------------------------------+
+------------------------------+---------------------------------------------+
| Pipeline | Rasterization |
+------------------------------+---------------------------------------------+
| |images_models| |br| | |rasterization_image| |
| |resampling| |br| | |
| |matching| |br| | |
| |triangulation| |br| | |
| |rasterization_circled| |br| | |
+------------------------------+---------------------------------------------+

Initial Input Digital Elevation Model
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For now, CARS uses an initial input Digital Elevation Model (:term:`DEM`) which is integrated in the stereo-rectification to minimize the disparity intervals to explore.
For now, CARS can use an initial input Digital Elevation Model (:term:`DEM`) which is integrated in the stereo-rectification to minimize the disparity intervals to explore.
Any geotiff file can be used.

The parameter is ``initial_elevation`` as seen in :ref:`configuration`.
Expand All @@ -124,43 +123,3 @@ Altimetric exploration and geometric inaccuracies
To reduce the search interval (i.e. altimetric exploration) in the matching step and thus save computing time, a faster sparse matching step is typically used. This matching step also enables geometric errors to be corrected, thus ensuring that the epipolar geometry (based on these models) is correct.

Matching can be performed with keypoints like `SIFT <https://www.cs.ubc.ca/~lowe/papers/ijcv04.pdf>`_.

.. _matching_sparse:

+--------------------------+---------------------------------------------+
| Pipeline | Matching (sparse) |
+--------------------------+---------------------------------------------+
| |images_models| |br| | |matching_spa_image| |
| |resampling| |br| | |
| |matching_spa| |br| | |
| |triangulation_spa| |br| | |
| |rasterization_spa| |br| | |
+--------------------------+---------------------------------------------+

The result is a sparse point cloud...

.. _triangulation_sparse:

+--------------------------+---------------------------------------------+
| Pipeline | Triangulation (sparse) |
+--------------------------+---------------------------------------------+
| |images_models| |br| | |triangulation_spa_image| |
| |resampling| |br| | |
| |matching_spa| |br| | |
| |triangulation_spa| |br| | |
| |rasterization_spa| |br| | |
+--------------------------+---------------------------------------------+

and a sparse digital surface model.

.. _rasterization_sparse:

+--------------------------+---------------------------------------------+
| Pipeline | Rasterization (sparse) |
+--------------------------+---------------------------------------------+
| |images_models| |br| | |rasterization_spa_image| |
| |resampling| |br| | |
| |matching_spa| |br| | |
| |triangulation_spa| |br| | |
| |rasterization_spa| |br| | |
+--------------------------+---------------------------------------------+
8 changes: 4 additions & 4 deletions docs/source/exploring_the_field/in_a_nutshell.rst
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Satellite photogrammetry in a nutshell
======================================

As its name suggests, satellite photogrammetry works using optical satellite acquisitions to generate a Digital Surface Model, the 2.5D representation created from observed surface altitude data. We speak of 2.5D because the digital surface model is an array of pixels (raster, 2D) where each pixel (x,y) corresponds to an altitude (z).
As its name suggests, satellite photogrammetry works using optical satellite acquisitions to generate a Digital Surface Model (DSM), the 2.5D representation created from observed surface altitude data. We speak of 2.5D because the digital surface model is an array of pixels (raster, 2D) where each pixel (x,y) corresponds to an altitude (z).

.. figure:: ../images/2D5.drawio.png
:width: 40%
Expand All @@ -12,7 +12,7 @@ As its name suggests, satellite photogrammetry works using optical satellite acq
On the left, an example of an array of pixels, and on the right, a volume representation of altitude values.


Like our eyes, altitude (or depth relative to the satellite, to continue the analogy) is determined from the observed pixels displacement. We therefore need at least two images, acquired from two different viewpoints. This difference in viewpoint between two satellites is quantified by the B over H ratio where B is the distance between the two satellites and H is their altitude.
Like our eyes, altitude (or depth relative to the satellite, to continue the analogy) is determined from the observed pixels displacement. We therefore need at least two images, acquired from two different viewpoints. This difference in viewpoints between two satellites is quantified by the B over H ratio where B is the distance between the two satellites and H is their altitude.

.. |nutimages| image:: ../images/nutshell_images.gif
:width: 60%
Expand All @@ -25,11 +25,11 @@ Like our eyes, altitude (or depth relative to the satellite, to continue the ana
| |b_over_h| | |nutimages| |
+-----------------+----------------+

Every raster `GDAL`_ knows how to read can be given as CARS input. In addition to images, the photogrammetric process requires geometric models. Rational Polynomial Coefficients (RPCs) provide a compact representation of a ground-to-image geometry giving a relationship between:
Every raster readable by `GDAL`_ can be given as CARS input. In addition to images, the photogrammetric process requires geometric models. Rational Polynomial Coefficients (RPCs) provide a compact representation of a ground-to-image geometry giving a relationship between:

- Image coordinates + altitude and ground coordinates (direct model: image to ground)
- Ground coordinates + altitude and image coordinates (inverse model: ground to image)

These coefficients are classically contained in the RPC*XML files.
These coefficients are classically contained in the RPC*.XML files.

.. _`GDAL`: https://gdal.org/
6 changes: 3 additions & 3 deletions docs/source/exploring_the_field/masks_and_classifications_usage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,12 @@ Masks
-----

| CARS can use a mask for each image in order to ignore some image regions (for instance water mask). This mask is taken into account during the whole 3D restitution process.
| The masks have one band with 1 nbit and the non zeros values will be considered as invalid data and theses areas will not processed during the computation.
| The masks have one band with 1 nbit and the non zeros values will be considered as invalid data and theses areas will not be processed during the computation.
| Please, see the section :ref:`convert_image_to_binary_image` to make a binary image.
| The mask are resampled in epipolar geometry with the resampling application.
| The masks are resampled in epipolar geometry with the resampling application.
| The masked values are not taken into account in the matching process (sparse or dense matching method) to avoid mismatch and useless processing.
| Further, the sparse matching estimation of the disparity range can be enhanced with mask using for the water area typicaly.
| Furthermore, the sparse matching estimation of the disparity range can be enhanced with mask using for the water area typicaly.
Classification
--------------
Expand Down
36 changes: 15 additions & 21 deletions docs/source/getting_started.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,29 +45,23 @@ Getting Started
.. sourcecode:: text

{
"inputs": {
"sensors" : {
"one": {
"image": "img1.tif",
"geomodel": "img1.geom",
"color": "color1.tif"
},
"two": {
"image": "img2.tif",
"geomodel": "img2.geom"
},
"three": {
"image": "img3.tif",
"geomodel": "img3.geom"
}
"inputs": {
"sensors" : {
"one": {
"image": "img1.tif",
"geomodel": "img1.geom",
"color": "color1.tif"
},
"pairing": [["one", "two"],["one", "three"]],
"initial_elevation": "srtm_dir/N29E031_KHEOPS.tif"
},

"output": {
"out_dir": "outresults"
"two": {
"image": "img2.tif",
"geomodel": "img2.geom"
}
}
},

"output": {
"directory": "outresults"
}
}

* Go to the ``data_gizeh/outresults/`` output directory to get a :term:`DSM` and color image associated.
Expand Down
Loading

0 comments on commit ac423d6

Please sign in to comment.