Skip to content

Commit 712c273

Browse files
committed
docs: update and clean README to ease reading
1 parent 2e8faa9 commit 712c273

File tree

1 file changed

+52
-56
lines changed

1 file changed

+52
-56
lines changed

README.md

+52-56
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,48 @@
1-
<h1 align="center">
2-
<a href="https://pandora.readthedocs.io/?badge=latest"><img src="https://raw.githubusercontent.com/CNES/Pandora/master/docs/source/Images/logo/logo_typo_large.png?inline=false" alt="Pandora Stereo Framework" width="432"></a>
3-
</h1>
4-
5-
<h4 align="center">A stereo matching framework that will help you design your stereo matching pipeline with state of the art performances.</h4>
6-
7-
<p align="center">
8-
<a><img src="https://github.com/CNES/Pandora/actions/workflows/pandora_ci.yml/badge.svg?branch=master"></a>
9-
<a href="https://codecov.io/gh/CNES/Pandora"><img src="https://codecov.io/gh/CNES/Pandora/branch/master/graph/badge.svg?token=IENWO02GB3"/></a>
10-
<a href='https://pandora.readthedocs.io/?badge=latest'><img src='https://readthedocs.org/projects/pandora/badge/?version=latest' alt='Documentation Status' /></a>
11-
<a href="https://opensource.org/licenses/Apache-2.0/"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg"></a>
12-
<a href="https://mybinder.org/v2/gh/CNES/Pandora/master"><img src="https://mybinder.org/badge_logo.svg"></a>
13-
</p>
14-
15-
<p align="center">
1+
<div align="center">
2+
<a target="_blank" href="https://github.com/CNES/pandora">
3+
<picture>
4+
<img
5+
src="https://raw.githubusercontent.com/CNES/Pandora/master/docs/source/Images/logo/logo_typo_large.png?inline=false""
6+
alt="Pandora"
7+
width="40%"
8+
/>
9+
</picture>
10+
</a>
11+
12+
<h4> Pandora, a stereo matching framework</h4>
13+
14+
[![Python](https://img.shields.io/badge/python-v3.8+-blue.svg)](https://www.python.org/downloads/release/python-390/)
15+
[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-orange.svg)](CONTRIBUTING.md)
16+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0/)
17+
[![Documentation](https://readthedocs.org/projects/pandora/badge/?version=latest)](https://pandora.readthedocs.io/)
18+
[![Github Action](https://github.com/CNES/Pandora/actions/workflows/pandora_ci.yml/badge.svg?branch=master)](https://github.com/CNES/Pandora/actions)
19+
[![Codecov](https://codecov.io/gh/CNES/Pandora/branch/master/graph/badge.svg?token=IENWO02GB3)](https://codecov.io/gh/CNES/Pandora)
20+
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/CNES/Pandora/master)
21+
22+
<p>
1623
<a href="#overview">Overview</a> •
1724
<a href="#install">Install</a> •
18-
<a href="#firststep">First Step</a> •
19-
<a href="#customize">Customize</a> •
25+
<a href="#quick-start">Quick Start</a> •
26+
<a href="#Documentation">Documentation</a> •
2027
<a href="#credits">Credits</a> •
2128
<a href="#related">Related</a> •
2229
<a href="#references">References</a>
2330
</p>
2431

32+
</div>
2533

2634
## Overview
2735

2836
From stereo rectified images to disparity map | Pandora is working with cost volumes
2937
:-------------------------:|:-------------------------:
3038
![](https://raw.githubusercontent.com/CNES/Pandora/master/docs/source/Images/schema_readme.png?inline=false) | ![](https://raw.githubusercontent.com/CNES/Pandora/master/docs/source/Images/disparity3D_with_projected_dispartiry_color.gif)
3139

40+
Pandora is a stereo matching flexible framework made for research and production with state of the art performances:
3241

33-
Pandora aims at shortening the path between a stereo-matching prototype and its industrialized version.
34-
By providing a modular pipeline inspired from the (Scharstein et al., 2002) taxonomy, it allows one to emulate, analyse and hopefully improve state of the art stereo algorithms with a few lines of code.
35-
36-
We (CNES) have actually been using Pandora to create the stereo matching pipeline for the CNES & Airbus <a href="https://co3d.cnes.fr/en/co3d-0"><img src="https://raw.githubusercontent.com/CNES/Pandora/master/docs/source/Images/logo_co3D_cnes.jpg" width="32" height="32"/></a> off board processing chain.
37-
Leaning on Pandora's versatility and a fast-paced constantly evolving field we are still calling this framework a work in progress !
42+
- Inspired from the (Scharstein et al., 2002) modular taxonomy, it allows one to emulate, analyse and hopefully improve state of the art stereo algorithms with a few lines of code.
43+
- For production purpose, Pandora have been created for the CNES & Airbus <a href="https://co3d.cnes.fr/en/co3d-0">CO3D project</a> processing chain, as [CARS](https://github.com/CNES/CARS) core stereo matching tool.
3844

39-
<img src="https://raw.githubusercontent.com/CNES/Pandora/master/docs/source/Images/pandora_first_step_terminal.gif" width="500"/>
45+
The tool is open for contributions, contact us to pandora AT cnes.fr !
4046

4147
## Install
4248

@@ -46,64 +52,54 @@ Pandora is available on Pypi and can be installed by:
4652
pip install pandora
4753
```
4854

49-
For stereo reconstruction we invite you to install pandora **and** the required plugins using instead the following shortcut:
55+
For stereo reconstruction, install pandora **with** following plugins:
5056

5157
```bash
52-
pip install pandora[sgm, mccnn]
58+
# SGM regularization
59+
pip install pandora[sgm]
60+
# MCCNN AI matching cost capability (heavy!)
61+
pip install pandora[mccnn]
5362
```
5463

55-
## First step
56-
57-
Pandora requires a `config.json` to declare the pipeline and the stereo pair of images to process.
58-
Download our data sample to start right away !
59-
- [cones stereo pair](https://raw.githubusercontent.com/CNES/Pandora/master/data_samples/images/cones.zip)
60-
- [a configuration file](https://raw.githubusercontent.com/CNES/Pandora/master/data_samples/json_conf_files/a_local_block_matching.json)
64+
## Quick Start
6165

6266
```bash
63-
# install pandora latest release
64-
pip install pandora
6567

66-
# download data samples
67-
wget https://raw.githubusercontent.com/CNES/Pandora/master/data_samples/images/cones.zip # input stereo pair
68-
wget https://raw.githubusercontent.com/CNES/Pandora/master/data_samples/json_conf_files/a_local_block_matching.json # configuration file
68+
# Download configuration file
69+
wget https://raw.githubusercontent.com/CNES/Pandora/master/data_samples/json_conf_files/a_local_block_matching.json
70+
71+
# Download data samples
72+
wget https://raw.githubusercontent.com/CNES/Pandora/master/data_samples/images/cones.zip
6973

70-
# uncompress data
74+
# Uncompress data
7175
unzip cones.zip
7276

73-
# run pandora
77+
# Run pandora
7478
pandora a_local_block_matching.json output_dir
7579

76-
#Left (respectively right) disparity map is saved in output_dir/left_disparity.tif (respectively output_dir/right_disparity.tif)
80+
# Left and right disparity maps are saved in output_dir: left_disparity.tif and right_disparity.tif
7781
```
7882

79-
## To go further
83+
## Documentation
8084

81-
To create you own stereo matching pipeline and choose among the variety of algorithms we provide, please consult [our online documentation](https://pandora.readthedocs.io/en/stable/index.html).
82-
83-
You will learn:
84-
- which stereo matching steps you can [use and combine](https://pandora.readthedocs.io/en/stable/userguide/step_by_step.html)
85-
- how to quickly set up a [Pandora pipeline](https://pandora.readthedocs.io/en/stable/userguide/sequencing.html)
86-
- how to add your own private algorithms to [customize your Pandora Framework](https://pandora.readthedocs.io/en/stable/developer_guide/your_plugin.html)
87-
- how to use [Pandora API](https://pandora.readthedocs.io/en/stable/userguide/as_an_api.html) (see [CARS](https://github.com/CNES/CARS) for real life example)
85+
To go further, please consult [our online documentation](https://pandora.readthedocs.io/).
8886

8987
## Credits
9088

91-
Our data test sample is based on the 2003 Middleburry dataset (D. Scharstein & R. Szeliski, 2003).
92-
93-
*(D. Scharstein & R. Szeliski, 2002). Scharstein, D., & Szeliski, R. (2002). A taxonomy and evaluation of dense two-frame stereo correspondence algorithms. International journal of computer vision, 47(1-3), 7-42.*
94-
*(D. Scharstein & R. Szeliski, 2003). Scharstein, D., & Szeliski, R. (2003, June). High-accuracy stereo depth maps using structured light. In 2003 IEEE Computer Society Conference on Computer Vision and Pattern Recognition, 2003. Proceedings. (Vol. 1, pp. I-I). IEEE.*
89+
- *Scharstein, D., & Szeliski, R. (2002). A taxonomy and evaluation of dense two-frame stereo correspondence algorithms. International journal of computer vision, 47(1-3), 7-42.*
90+
- *Scharstein, D., & Szeliski, R. (2003, June). High-accuracy stereo depth maps using structured light. In IEEE Computer Society Conference on Computer Vision and Pattern Recognition, 2003. Proceedings. (Vol. 1, pp. I-I).*
91+
- *2003 Middleburry dataset (D. Scharstein & R. Szeliski, 2003).*
9592

9693
## Related
9794

9895
[Plugin_LibSGM](https://github.com/CNES/pandora_plugin_libsgm) - Stereo Matching Algorithm plugin for Pandora
9996
[Plugin_MC-CNN](https://github.com/CNES/pandora_plugin_mccnn) - MC-CNN Neural Network plugin for Pandora
97+
[Pandora2D](https://github.com/CNES/Pandora2D) - CNES Image Registration framework based on Pandora, with 2D disparity maps.
10098
[CARS](https://github.com/CNES/CARS) - CNES 3D reconstruction software
10199

102100
## References
103101

104-
Please cite the following paper when using Pandora:
105-
*Cournet, M., Sarrazin, E., Dumas, L., Michel, J., Guinet, J., Youssefi, D., Defonte, V., Fardet, Q., 2020. Ground-truth generation and disparity estimation for optical satellite imagery. ISPRS - International Archives of the Photogrammetry, Remote Sensing and Spatial Information Sciences.*
106-
107-
108-
102+
Please cite the following papers when using Pandora:
109103

104+
- *Cournet, M., Sarrazin, E., Dumas, L., Michel, J., Guinet, J., Youssefi, D., Defonte, V., Fardet, Q., 2020. Ground-truth generation and disparity estimation for optical satellite imagery. ISPRS - International Archives of the Photogrammetry, Remote Sensing and Spatial Information Sciences.*
105+
- *Youssefi D., Michel, J., Sarrazin, E., Buffe, F., Cournet, M., Delvit, J., L’Helguen, C., Melet, O., Emilien, A., Bosman, J., 2020. Cars: A photogrammetry pipeline using dask graphs to construct a global 3d model. IGARSS - IEEE International Geoscience and Remote Sensing Symposium.*

0 commit comments

Comments
 (0)