Merge branch '60-catchy_readme' into 'develop'

Catchy README

See merge request nicolasnn/pyotb!107

README.md

-# pyotb: a pythonic extension of Orfeo Toolbox
+# pyotb: Orfeo ToolBox for Python
 
 [![latest release](https://gitlab.orfeo-toolbox.org/nicolasnn/pyotb/-/badges/release.svg)](https://gitlab.orfeo-toolbox.org/nicolasnn/pyotb/-/releases)
 [![pipeline status](https://gitlab.orfeo-toolbox.org/nicolasnn/pyotb/badges/develop/pipeline.svg)](https://gitlab.orfeo-toolbox.org/nicolasnn/pyotb/-/commits/develop)
 [![coverage report](https://gitlab.orfeo-toolbox.org/nicolasnn/pyotb/badges/develop/coverage.svg)](https://gitlab.orfeo-toolbox.org/nicolasnn/pyotb/-/commits/develop)
 [![read the docs status](https://readthedocs.org/projects/pyotb/badge/?version=master)](https://pyotb.readthedocs.io/en/master/)
 
-**pyotb** wraps the [Orfeo Toolbox](https://www.orfeo-toolbox.org/) (OTB)
-python bindings to make it more developer friendly.  
+**pyotb** wraps the [Orfeo Toolbox](https://www.orfeo-toolbox.org/) in a pythonic, developer friendly 
+fashion.  
 
 ## Key features
 
-- Easy use of OTB applications from python
+- Easy use of Orfeo ToolBox (OTB) applications from python
 - Simplify common sophisticated I/O features of OTB
-- Lazy execution of in-memory pipelines with OTB streaming mechanism
-- Interoperable with popular python libraries (numpy, rasterio)
+- Lazy execution of operations thanks to OTB streaming mechanism
+- Interoperable with popular python libraries ([numpy](https://numpy.org/) and 
+[rasterio](https://rasterio.readthedocs.io/))
 - Extensible
 
 Documentation hosted at [pyotb.readthedocs.io](https://pyotb.readthedocs.io/).
@@ -25,44 +26,23 @@ Building a simple pipeline with OTB applications
 ```py
 import pyotb
 
-# RigidTransformResample application, with input parameters as dict
+# RigidTransformResample, with input parameters as dict
 resampled = pyotb.RigidTransformResample({
-    "in": "https://some.remote.data/input.tif",  # Note: no /vsicurl/...
+    "in": "https://myserver.ia/input.tif",  # Note: no /vsicurl/
     "interpolator": "linear", 
     "transform.type.id.scaley": 0.5,
     "transform.type.id.scalex": 0.5
 })
 
-# OpticalCalibration, with automatic input parameters resolution
+# OpticalCalibration, with input parameters as args
 calib = pyotb.OpticalCalibration(resampled)
 
-# BandMath, with input parameters passed as kwargs
+# BandMath, with input parameters as kwargs
 ndvi = pyotb.BandMath(calib, exp="ndvi(im1b1, im1b4)")
 
-# Pythonic slicing using lazy computation (no memory used)
+# Pythonic slicing
 roi = ndvi[20:586, 9:572]
 
-# Pipeline execution
-# The actual computation happens here !
+# Pipeline execution. The actual computation happens here!
 roi.write("output.tif", "float")
 ```
-
-pyotb's objects also enable easy interoperability with 
-[numpy](https://numpy.org/) and [rasterio](https://rasterio.readthedocs.io/):
-
-```python
-# Numpy and RasterIO style attributes
-print(roi.shape, roi.dtype, roi.transform)
-print(roi.metadata)
-
-# Other useful information
-print(roi.get_infos())
-print(roi.get_statistics())
-
-array = roi.to_numpy()
-array, profile = roi.to_rasterio()
-```
-
-## Contributing
-
-Contributions are welcome on [Github](https://github.com/orfeotoolbox/pyotb) or the source repository hosted on the Orfeo ToolBox [GitLab](https://gitlab.orfeo-toolbox.org/nicolasnn/pyotb).

doc/features.md

@@ -92,4 +92,94 @@ attribute:
 
 ```python
 inp.transform  # (6.0, 0.0, 760056.0, 0.0, -6.0, 6946092.0)
+```
+
+### Metadata
+
+Images metadata can be retrieved with the `metadata` attribute:
+
+```python
+print(inp.metadata)
+```
+
+Gives: 
+
+```
+{
+  'DataType': 1.0, 
+  'DriverLongName': 'GeoTIFF', 
+  'DriverShortName': 'GTiff', 
+  'GeoTransform': (760056.0, 6.0, 0.0, 6946092.0, 0.0, -6.0),
+  'LowerLeftCorner': (760056.0, 6944268.0), 
+  'LowerRightCorner': (761562.0, 6944268.0), 
+  'AREA_OR_POINT': 'Area', 
+  'TIFFTAG_SOFTWARE': 'CSinG - 13 SEPTEMBRE 2012', 
+  'ProjectionRef': 'PROJCS["RGF93 v1 / Lambert-93",\n...',
+  'ResolutionFactor': 0, 
+  'SubDatasetIndex': 0, 
+  'UpperLeftCorner': (760056.0, 6946092.0), 
+  'UpperRightCorner': (761562.0, 6946092.0), 
+  'TileHintX': 251.0, 
+  'TileHintY': 8.0
+}
+```
+
+## Information
+
+The information fetched by the `ReadImageInfo` OTB application is available 
+through `get_info()`:
+
+```python
+print(inp.get_info())
+```
+
+Gives:
+
+```json lines
+{
+  'indexx': 0, 
+  'indexy': 0, 
+  'sizex': 251, 
+  'sizey': 304, 
+  'spacingx': 6.0, 
+  'spacingy': -6.0, 
+  'originx': 760059.0, 
+  'originy': 6946089.0, 
+  'estimatedgroundspacingx': 5.978403091430664, 
+  'estimatedgroundspacingy': 5.996793270111084, 
+  'numberbands': 4, 
+  'datatype': 'unsigned_char', 
+  'ullat': 0.0, 
+  'ullon': 0.0, 
+  'urlat': 0.0, 
+  'urlon': 0.0, 
+  'lrlat': 0.0, 
+  'lrlon': 0.0, 
+  'lllat': 0.0, 
+  'lllon': 0.0, 
+  'rgb.r': 0, 
+  'rgb.g': 1, 
+  'rgb.b': 2, 
+  'projectionref': 'PROJCS["RGF93 v1 ..."EPSG","2154"]]',
+  'gcp.count': 0
+}
+```
+
+## Statistics
+
+Image statistics can be computed on-the-fly using `get_statistics()`:
+
+```python
+print(inp.get_statistics())
+```
+
+Gives:
+
+```json lines
+{
+  'out.mean': [79.5505, 109.225, 115.456, 249.349], 
+  'out.min': [33, 64, 91, 47], 
+  'out.max': [255, 255, 230, 255], 
+  'out.std': [51.0754, 35.3152, 23.4514, 20.3827]
+}
 ```
\ No newline at end of file

doc/index.md

-# Pyotb: Orfeo Toolbox for Python
+# pyotb: Orfeo Toolbox for Python
 
 pyotb is a Python extension of Orfeo Toolbox. It has been built on top of the 
 existing Python API of OTB, in order 
@@ -9,7 +9,7 @@ to make OTB more Python friendly.
 ## Get started
 
 - [Installation](installation.md)
-- [How to use pyotb](quickstart.md)
+- [Quick start](quickstart.md)
 - [Useful features](features.md)
 - [Functions](functions.md)
 - [Interaction with Python libraries (numpy, rasterio, tensorflow)](interaction.md)
@@ -27,8 +27,17 @@ to make OTB more Python friendly.
 - [Managing loggers](managing_loggers.md)
 - [Troubleshooting & limitations](troubleshooting.md)
 
-
 ## API
 
 - See the API reference. If you have any doubts or questions, feel free to ask
-on github or gitlab!
\ No newline at end of file
+on github or gitlab!
+
+## Contribute
+
+Contributions are welcome !
+Open a PR/MR, or file an issue if you spot a bug or have any suggestion:
+
+- [Github](https://github.com/orfeotoolbox/pyotb) 
+- [Orfeo ToolBox GitLab instance](https://gitlab.orfeo-toolbox.org/nicolasnn/pyotb).
+
+Thank you!
\ No newline at end of file