Tutorial input-output

modules/python/doc/rst/tutorials/image/examples/code-image-io.rst

@@ -0,0 +1,8 @@
+.. _code-image-io:
+
+tutorial-image-io.py
+=========================
+
+.. literalinclude:: /examples/image/tutorial-image-io.py
+	:language: python
+	:linenos:

modules/python/doc/rst/tutorials/image/tutorial-image-display.rst

@@ -58,7 +58,7 @@ as well as the :py:class:`~visp.core.Display` class and the
 
 .. literalinclude:: /examples/image/tutorial-image-display.py
   :language: python
-  :end-before: # Image path
+  :end-at: from visp.python.display_utils import get_display
 
 .. note::
 
@@ -72,8 +72,8 @@ We then import the image from the disk as the :py:class:`~visp.core.ImageRGBa` o
 
 .. literalinclude:: /examples/image/tutorial-image-display.py
   :language: python
-  :start-after: # Image path
-  :end-before: # Create the display
+  :start-at: # Image path
+  :end-at:   sys.exit()
 
 .. note::
 
@@ -86,24 +86,24 @@ and set the title of the display using :py:meth:`~visp.core.Display.setTitle`:
 
 .. literalinclude:: /examples/image/tutorial-image-display.py
    :language: python
-   :start-after: # Create the display
-   :end-before: # Display the image
+   :start-at: # Create the display
+   :end-at: Display.setTitle(I, "monkey.jpeg")
 
 The image is then drawn in the display with the :py:class:`~visp.core.Display` method.
 The :py:meth:`~visp.core.Display.flush` method finally shows the window on screen:
 
 .. literalinclude:: /examples/image/tutorial-image-display.py
   :language: python
-  :start-after: # Display the image
-  :end-before: # Wait for user input
+  :start-at: # Display the image
+  :end-at: Display.flush(I)
 
 The :py:meth:`~visp.core.Display.flush` method does not stop the program execution.
 We therefore call the :py:meth:`~visp.core.Display.getClick` method, to
 pause the program until the user clicks in the display:
 
 .. literalinclude:: /examples/image/tutorial-image-display.py
   :language: python
-  :start-after: # Wait for user input
+  :start-at: # Wait for user input
 
 Other Options
 ===========================
@@ -134,8 +134,8 @@ To scale the image automatically so that it fits on the screen, call
 
 .. literalinclude:: /examples/image/tutorial-image-display-scaled-auto.py
   :language: python
-  :start-after: # Set Downscaling factor
-  :end-before: # Continue creating the display 
+  :start-at: # Set Downscaling factor
+  :end-at: d.setDownScalingFactor(Display.SCALE_AUTO)
 
 You can test this behavior with the following :ref:`example <code-image-display-scaled-auto>`:
 
@@ -148,8 +148,8 @@ code divides the image width and height by five:
 
 .. literalinclude:: /examples/image/tutorial-image-display-scaled-manu.py
   :language: python
-  :start-after: # Set Downscaling factor
-  :end-before: # Continue creating the display 
+  :start-at: # Set Downscaling factor
+  :end-at: d.setDownScalingFactor(Display.SCALE_5) 
 
 You can test this behavior with the following :ref:`example <code-image-display-scaled-manu>`:
 
@@ -169,14 +169,14 @@ You can also use Matplotlib to display the image. First, import
 
 .. literalinclude:: /examples/image/tutorial-image-display-matplotlib.py
   :language: python
-  :start-after: # import matplotlib
-  :end-before: # import ViSP bindings
+  :start-at: import matplotlib.pyplot as plt
+  :end-at: import matplotlib.pyplot as plt
 
 Then display the image in a figure:
 
 .. literalinclude:: /examples/image/tutorial-image-display-matplotlib.py
   :language: python
-  :start-after: # Display using Matplotlib
+  :start-at: # Display using Matplotlib
 
 The following :ref:`example <code-image-display-matplotlib>` shows this approach:
 

modules/python/doc/rst/tutorials/image/tutorial-image-drawings.rst

@@ -0,0 +1,5 @@
+.. _tutorial-image-drawings:
+
+=================================
+Insert basic drawings in an image
+=================================

modules/python/doc/rst/tutorials/image/tutorial-image-io.rst

@@ -2,4 +2,121 @@
 
 ============================
 Read and write an image file
-============================
+============================
+
+Introduction
+===========================
+
+Goal
+---------------------------
+
+In this tutorial you will learn how to:
+
+- Read an image from a file
+- Write an image to a file.
+- Use the :py:class:`~visp.io.ImageIo` class.
+
+Prerequisites
+---------------------------
+
+You should first read the :ref:`Getting started with images <tutorial-image-getting-started>` tutorial.
+
+Read and write an image file
+============================
+
+Code
+---------------------------
+
+The following :ref:`example <code-image-io>` reads the ``monkey.jpeg`` file, converts it into a grayscale image,
+and saves the result as ``grayscale_monkey.jpeg``:
+
+.. literalinclude:: /examples/image/tutorial-image-io.py
+	:language: python
+	:linenos:
+
+You can run the example with:
+
+.. code-block:: bash
+
+	python3 $VISP_WS/visp/modules/python/examples/image/tutorial-image-io.py
+
+Result
+---------------------------
+
+The example displays the input image followed by the converted grayscale image: 
+
+.. list-table::
+
+  * - .. image:: images/result-image-io-input.png
+
+    - .. image:: images/result-image-io-output.png
+
+The input and output images are available in:
+
+.. code-block:: text
+
+   $VISP_WS/visp/modules/python/examples/image
+
+Explanation
+---------------------------
+
+We first import the classes required to create, convert and display images.
+We also import :py:class:`~visp.io.ImageIo`,
+which we use to read and write image files:
+
+.. literalinclude:: /examples/image/tutorial-image-io.py
+  :language: python
+  :end-at: from visp.io import ImageIo
+
+We define a helper function to display the images that we manipulate:
+
+.. literalinclude:: /examples/image/tutorial-image-io.py
+  :language: python
+  :start-at: # Function displaying an image
+  :end-at:   Display.getClick(I)
+
+.. note::
+
+  For a more detailed explanation of how displays work in ViSP, see the :ref:`Display an image <tutorial-image-display>` tutorial.
+
+We then read the image ``monkey.jpeg`` using the :py:meth:`~visp.io.ImageIo.read` method.
+We use an exception handler so that we can stop the program in case the reading fails because the remaining operations require a valid input image:
+
+.. literalinclude:: /examples/image/tutorial-image-io.py
+  :language: python
+  :start-at: # Read the image
+  :end-at:   sys.exit()
+
+We display the loaded image with the helper function defined previously:
+
+.. literalinclude:: /examples/image/tutorial-image-io.py
+  :language: python
+  :start-at: # Display the loaded image
+  :end-at: display(I, "Loaded image")
+
+We convert the input image into a grayscale image with:
+
+.. literalinclude:: /examples/image/tutorial-image-io.py
+  :language: python
+  :start-at: # Convert the image into a grayscale image
+  :end-at: ImageConvert.convert(I, Igray)
+
+We write the grayscale image to the ``grayscale_monkey.jpeg`` file with :py:meth:`~visp.io.ImageIo.write`.
+The exception handler is non-blocking this time, because further processing does not depend on the output file:
+
+.. literalinclude:: /examples/image/tutorial-image-io.py
+  :language: python
+  :start-at: # Write the image
+  :end-at:   print(e)
+
+
+Finally, we display the grayscale image:
+
+.. literalinclude:: /examples/image/tutorial-image-io.py
+  :language: python
+  :start-at: # Display the written image
+
+Next Tutorial
+===========================
+
+You are now ready to learn how to :ref:`Insert basic drawings in an image <tutorial-image-drawings>`.

modules/python/examples/image/tutorial-image-display-matplotlib.py

@@ -1,10 +1,8 @@
 import sys
 from pathlib import Path
 
-# import matplotlib
 import matplotlib.pyplot as plt
 
-# import ViSP bindings
 from visp.core import ImageRGBa
 from visp.io import ImageIo
 

modules/python/examples/image/tutorial-image-display-scaled-auto.py

@@ -12,7 +12,6 @@
 # Set Downscaling factor
 d.setDownScalingFactor(Display.SCALE_AUTO)
 
-# Continue creating the display
 d.init(I)
 Display.setTitle(I, "Automatic scale")
 

modules/python/examples/image/tutorial-image-display-scaled-manu.py

@@ -12,7 +12,6 @@
 # Set Downscaling factor
 d.setDownScalingFactor(Display.SCALE_5)
 
-# Continue creating the display
 d.init(I)
 Display.setTitle(I, "Manual scale")
 

modules/python/examples/image/tutorial-image-io.py

@@ -0,0 +1,49 @@
+import sys
+from pathlib import Path
+
+from visp.core import ImageGray, ImageRGBa, ImageConvert
+from visp.core import Display
+from visp.python.display_utils import get_display
+
+from visp.io import ImageIo
+
+# Function displaying an image
+def display(I, title):
+  # Display the image
+  d = get_display()
+  d.init(I)
+  Display.setTitle(I, title)
+  Display.display(I)
+  Display.flush(I)
+
+  # Wait for user input
+  print("A click to quit...")
+  Display.getClick(I)
+
+# Read the image
+inputPath = str(Path(__file__).parent) + "/monkey.jpeg"
+I = ImageRGBa()
+try:
+  ImageIo.read(I, inputPath)
+  print(f"Successfully loaded image: {inputPath}")
+except Exception as e:
+  print(e)
+  sys.exit()
+
+# Display the loaded image
+display(I, "Loaded image")
+
+# Convert the image into a grayscale image
+Igray = ImageGray()
+ImageConvert.convert(I, Igray)
+
+# Write the image
+outputPath = str(Path(__file__).parent) + "/grayscale_monkey.jpeg"
+try:
+  ImageIo.write(Igray, outputPath)
+  print(f"Image successfully written to '{outputPath}'")
+except Exception as e:
+  print(e)
+
+# Display the written image
+display(Igray, "Written image")