Adding an example notebook no how to convert hex geometry to square a…

…nd back (#767)

* Adding an example notebook no how to convert hex geometry to square and back

* Adding information in the docstring to use the  argument in the

* Adding example code in the docstring for  and

* simplified a bit this example and corrected the line length < 90 columns

ctapipe/image/geometry_converter_hex.py

@@ -306,7 +306,9 @@ def convert_geometry_hex1d_to_rect2d(geom, signal, key=None, add_rot=0):
     signal : ndarray
         1D (no timing) or 2D (with timing) array of the pmt signals
     key : (default: None)
-        arbitrary key to store the transformed geometry in a buffer
+        arbitrary key (float, string) to store the transformed geometry in a buffer
+        The geometries (hex and rect) will be stored in a buffer.
+        The key is necessary to make the conversion back from rect to hex.
     add_rot : int/float (default: 0)
         parameter to apply an additional rotation of `add_rot` times 60°
 
@@ -320,6 +322,13 @@ def convert_geometry_hex1d_to_rect2d(geom, signal, key=None, add_rot=0):
         rectangular grid
     rot_img : ndarray 2D (no timing) or 3D (with timing)
         the rectangular signal image
+
+    Example
+    -------
+    camera = event.inst.subarray.tel[tel_id].camera
+    image = event.r0.tel[tel_id].image[0]
+    key = camera.cam_id
+    square_geom, square_image = convert_geometry_hex1d_to_rect2d(camera, image, key=key)
     """
 
     if key in rot_buffer:
@@ -455,6 +464,7 @@ def convert_geometry_rect2d_back_to_hexe1d(geom, signal, key=None,
         pixel intensity stored in a 2D rectangular camera grid
     key:
         key to retrieve buffered geometry information
+        (see `convert_geometry_hex1d_to_rect2d`)
     add_rot:
         not used -- only here for backwards compatibility
 
@@ -473,6 +483,15 @@ def convert_geometry_rect2d_back_to_hexe1d(geom, signal, key=None,
     instance of the original camera layout, which it tries to load by name (i.e.
     the `cam_id`). The function assumes the original `cam_id` can be inferred from the
     given, modified one by: `geom.cam_id.split('_')[0]`.
+
+    Example
+    -------
+    camera = event.inst.subarray.tel[tel_id].camera
+    image = event.r0.tel[tel_id].image[0]
+    key = camera.cam_id
+    square_geom, square_image = convert_geometry_hex1d_to_rect2d(camera, image, key=key)
+    hex_geom, hex_image = convert_geometry_rect2d_back_to_hexe1d(square_geom,
+    square_image, key = key)
     """
 
     if key not in rot_buffer: